> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Create a web monitor with a schedule and sources

> How to create a Keenable monitor: write the topic, limit it to the sites you trust, set a cron schedule, tag it with metadata and retry safely.

Create a monitor that watches the web for one topic and hands you the new pages on a schedule you pick. You describe the topic once, limit it to the sources you trust, and get a digest of new results at each run. For what a monitor is and every way to read it, see [Monitors](https://docs.keenable.ai/products/monitors).

You need an [API key](https://docs.keenable.ai/api-keys.md). Monitors has no keyless tier. An agent that signed in with AgentID creates its own key. Otherwise a person approves one login: have the agent run `keenable login` and show you the link and code, then approve it in the console. See [Get a key from an agent or the CLI](https://docs.keenable.ai/api-keys.md#get-a-key-from-an-agent-or-the-cli). After that, the agent uses the saved key without you.

## Request fields

A create request is a JSON body sent to `POST /v1/monitors`. Only `search.query` is required:

| Field | What it sets | Rules |
| - | - | - |
| `search.query` | The topic, in plain words | 1 to 2,000 characters |
| `search.max_results` | How many results a run returns at most | 1 to 100, default 10 |
| `search.include_domains` | Keep only pages from these hosts | A list of hosts, such as `["euractiv.com"]` |
| `search.exclude_domains` | Drop pages from these hosts | A list of hosts |
| `search.content.text` | Add each result's page text, its first 6,000 characters | `true` or `false` |
| `name` | A label for you and your team | Up to 200 characters |
| `schedule` | When runs happen: `cron`, `interval` or `once` | At most one run an hour. See [Schedules](https://docs.keenable.ai/products/monitors#schedules) |
| `webhook` | Where events go, and which events | A public HTTPS URL. The create response carries the signing secret. See [Receive monitor webhooks](https://docs.keenable.ai/guides/monitor-webhooks.md) |
| `metadata` | Your own string tags, sent back in every webhook event | At most 50 keys |
| `output_schema` | A JSON Schema for a summary of each run | See [What a run returns](https://docs.keenable.ai/products/monitors#what-a-run-returns) |
| `Idempotency-Key` header | Makes a retried create return the first monitor | Kept for 24 hours |

## Create a scheduled monitor

This sample creates a monitor for EU AI Act enforcement news from two sites. It runs at 9:00 Paris time on weekdays, returns up to 20 results per run, and carries a `team` tag. It prints the monitor's ID, its status and its next three run times:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable } from "keenable";

async function main() {
  // reads KEENABLE_API_KEY from the environment
  const client = new Keenable();
  const monitor = await client.monitors.create({
    name: "EU AI Act enforcement",
    search: {
      query: "EU AI Act enforcement actions and fines",
      maxResults: 20,
      includeDomains: ["euractiv.com", "reuters.com"],
    },
    schedule: { type: "cron", value: "0 9 * * 1-5", timezone: "Europe/Paris" },
    metadata: { team: "policy" },
    idempotencyKey: "eu-ai-act-enforcement-v1",
  });
  console.log(monitor.id, monitor.status);
  for (const runAt of monitor.upcomingRuns) {
    console.log(runAt);
  }
}

main();
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
from keenable import Keenable

# reads KEENABLE_API_KEY from the environment
client = Keenable()
monitor = client.monitors.create(
    name="EU AI Act enforcement",
    search={
        "query": "EU AI Act enforcement actions and fines",
        "max_results": 20,
        "include_domains": ["euractiv.com", "reuters.com"],
    },
    schedule={"type": "cron", "value": "0 9 * * 1-5", "timezone": "Europe/Paris"},
    metadata={"team": "policy"},
    idempotency_key="eu-ai-act-enforcement-v1",
)
print(monitor.id, monitor.status)
for run_at in monitor.upcoming_runs:
    print(run_at)
```

```go Go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/keenableai/keenable-sdk/go"
)

func main() {
	// reads KEENABLE_API_KEY from the environment
	client, err := keenable.New(nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	monitor, err := client.Monitors.Create(context.Background(), &keenable.MonitorCreateParams{
		Name: "EU AI Act enforcement",
		Search: keenable.MonitorSearchParams{
			Query:          "EU AI Act enforcement actions and fines",
			MaxResults:     20,
			IncludeDomains: []string{"euractiv.com", "reuters.com"},
		},
		Schedule:       &keenable.MonitorScheduleParams{Type: "cron", Value: "0 9 * * 1-5", Timezone: "Europe/Paris"},
		Metadata:       map[string]string{"team": "policy"},
		IdempotencyKey: "eu-ai-act-enforcement-v1",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(monitor.ID, monitor.Status)
	for _, runAt := range monitor.UpcomingRuns {
		fmt.Println(runAt)
	}
}
```

```rust Rust theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use std::collections::HashMap;

use keenable::{Client, MonitorCreateParams, MonitorScheduleParams, MonitorSearchParams};

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    // reads KEENABLE_API_KEY from the environment
    let client = Client::new()?;
    let monitor = client
        .monitors()
        .create(&MonitorCreateParams {
            name: Some("EU AI Act enforcement".into()),
            search: MonitorSearchParams {
                query: "EU AI Act enforcement actions and fines".into(),
                max_results: Some(20),
                include_domains: Some(vec!["euractiv.com".into(), "reuters.com".into()]),
                ..Default::default()
            },
            schedule: Some(MonitorScheduleParams {
                schedule_type: "cron".into(),
                value: Some("0 9 * * 1-5".into()),
                timezone: Some("Europe/Paris".into()),
            }),
            metadata: Some(HashMap::from([("team".to_string(), "policy".to_string())])),
            idempotency_key: Some("eu-ai-act-enforcement-v1".into()),
            ..Default::default()
        })
        .await?;
    println!("{} {}", monitor.id, monitor.status);
    for run_at in &monitor.upcoming_runs {
        println!("{run_at}");
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -X POST https://api.keenable.ai/v1/monitors \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eu-ai-act-enforcement-v1" \
  -d '{
    "name": "EU AI Act enforcement",
    "search": {
      "query": "EU AI Act enforcement actions and fines",
      "max_results": 20,
      "include_domains": ["euractiv.com", "reuters.com"]
    },
    "schedule": {"type": "cron", "value": "0 9 * * 1-5", "timezone": "Europe/Paris"},
    "metadata": {"team": "policy"}
  }'
```

The SDK tabs need SDK 0.2.0 or later, the first version with Monitors. If your package manager doesn't offer 0.2.0 yet, use the curl tab.

You see the ID, `active` and three run times in UTC. 9:00 in Paris is 08:00 UTC in winter:

```text Example output theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
mon_3kq9z2c8f1a04b7d9e6f5a21 active
2026-11-20T08:00:00.000Z
2026-11-23T08:00:00.000Z
2026-11-24T08:00:00.000Z
```

The create call takes a few seconds. The monitor starts empty and matches only pages crawled after you create it. Each run returns the results found since the previous run. To read them, see [Read monitor results](https://docs.keenable.ai/guides/read-monitor-results.md).

## Check that a new monitor works

A new monitor has no results for minutes to hours, so an empty list doesn't mean it is broken. To confirm the setup right away:

1. Check that the create response has `status: "active"` and a list of `upcoming_runs`. If the schedule was refused, the API returns `400` instead.
2. [Trigger a run](https://docs.keenable.ai/api-reference/monitors/trigger.md) and read it with [Get a run](https://docs.keenable.ai/api-reference/monitors/run.md). A run that found nothing new still completes, with no results.
3. If the monitor has a webhook, send it a signed sample event. See [Test your handler locally](https://docs.keenable.ai/guides/monitor-webhooks.md#test-your-handler-locally).

Then come back for results after the monitor has had time to match new pages.

## Reuse a monitor before you create one

Every API key in your organization sees the same monitors. Before you create a monitor, list the ones whose name contains your topic. This request returns active monitors with `AI Act` in their name:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -G https://api.keenable.ai/v1/monitors \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  --data-urlencode "name=AI Act" \
  --data-urlencode "status=active"
```

You get `{"data": [...], "has_more": false, "next_cursor": null}`. If `data` holds a monitor on your topic, use its `id` instead of creating another. To find monitors by tag, pass `metadata[team]=policy` instead of `name`. See [List monitors](https://docs.keenable.ai/api-reference/monitors/list.md).

## Retry a create safely

A create can time out after the monitor was made. Send the same `Idempotency-Key` header when you retry, so the retry returns the first monitor instead of creating a second one:

| You send | Within 24 hours of the first call, you get |
| - | - |
| The same key and the same body | `201` with the monitor the first call created, its `webhook.secret` and the header `Idempotent-Replayed: true` |
| The same key and a different body | `409` with `idempotency_conflict` |
| A new key, or no key | A new monitor |

Pick one key per monitor you mean to create, such as `eu-ai-act-enforcement-v1`. The SDKs send the key from `idempotency_key` (`idempotencyKey` in TypeScript, `IdempotencyKey` in Go).

## Change a monitor after you create it

Send only the fields that change to [Update a monitor](https://docs.keenable.ai/api-reference/monitors/update.md). The API merges `search` and `webhook` into the stored values. This request moves the run to 7:00 Paris time and keeps the query and sites:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -X PATCH https://api.keenable.ai/v1/monitors/mon_3kq9z2c8f1a04b7d9e6f5a21 \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule": {"type": "cron", "value": "0 7 * * 1-5", "timezone": "Europe/Paris"}}'
```

The response is the monitor with new `upcoming_runs`. To stop runs without losing results, send `{"status": "paused"}`. `{"schedule": null}` removes the schedule, and the monitor then runs only when you [trigger a run](https://docs.keenable.ai/api-reference/monitors/trigger.md).

## Common mistakes

| Wrong | Right | Why |
| - | - | - |
| `"query": "AI Act AND (fine OR penalty)"` | `"query": "EU AI Act enforcement actions and fines"` | The monitor reads the query as a topic, not as search operators. See [Write a good query](https://docs.keenable.ai/products/monitors#write-a-good-query). |
| `"value": "*/15 * * * *"` | `"value": "0 * * * *"` or slower | The API returns `400` with `a cron schedule may run at most once an hour`. |
| `{"type": "interval", "value": "6h", "timezone": "Europe/Paris"}` | `{"type": "interval", "value": "6h"}` | The API returns `400` with `schedule.timezone applies only to a cron schedule`. |
| `"url": "http://localhost:3000/hook"` | A public `https://` URL | The API returns `400` with `webhook.url must be a public HTTPS address`. |
| `"search": {"query": "...", "published_after": "7d"}` | Leave the field out | A monitor accepts only new pages already. Any search field other than `query`, `max_results`, `include_domains`, `exclude_domains` and `content.text` returns `400` with `monitor_option_not_supported`. |
| Creating the monitor, then reading `webhook.secret` later | Store `webhook.secret` from the create response | Only the create response carries the secret, or an update that adds a webhook to a monitor that had none. |

## API reference

* [Create a monitor](https://docs.keenable.ai/api-reference/monitors/create.md): every field and status code.
* [Get a monitor](https://docs.keenable.ai/api-reference/monitors/get.md): check `upcoming_runs` and the stored schedule.
* [Read monitor results](https://docs.keenable.ai/guides/read-monitor-results.md): poll results, read runs or let your agent read them.
* [Receive monitor webhooks](https://docs.keenable.ai/guides/monitor-webhooks.md): get each new page at your endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.