> ## 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

# Monitors: new web pages about any topic

> Get new pages about any topic as Keenable crawls them: over MCP, by webhook, or in scheduled runs. Free for now. Quickstart, webhooks, schedules and limits.

A monitor finds new pages about a topic as Keenable crawls them, so you don't have to run the same search again. Describe the topic once, such as `new open-weights LLM releases`. Keenable checks every page it crawls against your monitors. It keeps the pages that report something new about the topic, and only the first page of each story. Each page a monitor keeps is one of its results.

Monitors needs an [API key](https://docs.keenable.ai/api-keys.md). It has no keyless tier. If you don't send a key, the API returns `401` with `missing_api_key`, and the SDKs raise their authentication error before sending the request.

## Choose how to get results

A monitor gives you its results in four ways, and one monitor can use several of them.

| Way | What you get | Pick it if | Set it up with |
| - | - | - | - |
| Your agent | The results your agent hasn't seen yet, each one once | An agent reads the news for you, in chat or on a scheduled task | [`get_monitor_results`](https://docs.keenable.ai/mcp-server#monitors-tools) on the MCP server |
| Instant webhook events | Each new result, minutes after it's crawled | Your code acts on each result as it arrives | A `webhook`. It sends `monitor.result.found` unless `webhook.events` leaves it out |
| Runs | The results found since the previous run | You want a digest, such as every weekday at 9:00 | A [`schedule`](#schedules), or [Run a monitor now](https://docs.keenable.ai/api-reference/monitors/trigger.md) |
| Polling | Every result, newest first | You have no public endpoint and no schedule | [List results](https://docs.keenable.ai/api-reference/monitors/results.md) |

For an app, use a webhook with `monitor.result.found`. It's the fastest of the four, and it needs no polling loop.

## Try a monitor

With the [CLI](https://docs.keenable.ai/cli.md) installed and `keenable login` done, this command creates a monitor that runs once a day:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
keenable monitors create "new open-weights LLM releases" --every 1d
```

The CLI prints the new monitor with its `id`. Later, read its results, keeping only the important ones:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
keenable monitors results mon_123 --min-importance 4 -p
```

Replace `mon_123` with your monitor's `id`. Until the first results arrive, the command prints `No results yet. A new monitor only sees pages crawled after it was created.` See [CLI → Monitors](https://docs.keenable.ai/cli.md#monitors) for every subcommand.

In an MCP client such as Claude Code or Cursor, connected with an API key, ask your agent: "Create a Keenable monitor for new open-weights LLM releases." Your agent creates it with the `create_monitor` tool and can read the results later with `get_monitor_results`. See [Monitors tools](https://docs.keenable.ai/mcp-server.md#monitors-tools). To test `get_monitor_results` with curl, see [Call get\_monitor\_results directly](https://docs.keenable.ai/changelog/2026-11-mcp-monitors-tools.md#call-get_monitor_results-directly).

## Create a monitor

The Python, TypeScript and Rust samples on this page need SDK 0.2.0 or later, and the package registries hold older releases. The Go and curl samples work today. See [SDK versions](https://docs.keenable.ai/sdks.md#versions).

This sample creates a monitor for new open-weights model releases, with a webhook that gets each new result as a `monitor.result.found` event. It prints the monitor's ID, its status and the webhook's signing secret:

```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: "Open-weights LLM releases",
    search: { query: "new open-weights LLM releases" },
    webhook: {
      url: "https://hooks.example.com/keenable",
      events: ["monitor.result.found", "monitor.disabled"],
    },
  });
  console.log(monitor.id, monitor.status);
  console.log(monitor.webhook?.secret); // shown once: store it
}

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="Open-weights LLM releases",
    search={"query": "new open-weights LLM releases"},
    webhook={
        "url": "https://hooks.example.com/keenable",
        "events": ["monitor.result.found", "monitor.disabled"],
    },
)
print(monitor.id, monitor.status)
print(monitor.webhook.secret)  # shown once: store it
```

```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:   "Open-weights LLM releases",
		Search: keenable.MonitorSearchParams{Query: "new open-weights LLM releases"},
		Webhook: &keenable.MonitorWebhookParams{
			URL:    "https://hooks.example.com/keenable",
			Events: []string{"monitor.result.found", "monitor.disabled"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(monitor.ID, monitor.Status)
	if monitor.Webhook != nil && monitor.Webhook.Secret != nil {
		fmt.Println(*monitor.Webhook.Secret) // shown once: store it
	}
}
```

```rust Rust theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::{Client, MonitorCreateParams, MonitorSearchParams, MonitorWebhookParams};

#[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("Open-weights LLM releases".into()),
            search: MonitorSearchParams::new("new open-weights LLM releases"),
            webhook: Some(MonitorWebhookParams {
                url: Some("https://hooks.example.com/keenable".into()),
                events: Some(vec!["monitor.result.found".into(), "monitor.disabled".into()]),
            }),
            ..Default::default()
        })
        .await?;
    println!("{} {}", monitor.id, monitor.status);
    if let Some(webhook) = monitor.webhook {
        println!("{}", webhook.secret.unwrap_or_default()); // shown once: store it
    }
    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: open-weights-llm-releases" \
  -d '{
    "name": "Open-weights LLM releases",
    "search": {"query": "new open-weights LLM releases"},
    "webhook": {
      "url": "https://hooks.example.com/keenable",
      "events": ["monitor.result.found", "monitor.disabled"]
    }
  }'
```

You see the new monitor's ID, `active` and the secret:

```text Example output theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
mon_3kq9z2c8f1a04b7d9e6f5a21 active
whsec_example
```

> [!WARNING]
>
> Only two responses carry `webhook.secret`: the create response, and the response to an [update](https://docs.keenable.ai/api-reference/monitors/update.md) that adds a webhook to a monitor that had none. Store it where your webhook handler can read it before you do anything else.

Creating a monitor takes a few seconds. The monitor starts empty. It matches only pages crawled after you create it, so the first results arrive minutes to hours later, depending on how often the topic is written about. A monitor doesn't backfill older pages. Use [Search](https://docs.keenable.ai/products/search.md) for what's already published.

For a monitor with a schedule, chosen sources and metadata, see [Create a monitor](https://docs.keenable.ai/guides/create-a-monitor.md).

The `Idempotency-Key` header makes a retried create safe. Within 24 hours, the same key with the same body returns the monitor the first call created instead of creating a second one. The same key with a different body returns `409` with `idempotency_conflict`.

## Write a good query

The query decides which pages the monitor keeps. Write it as a topic in plain words, the way you'd describe it to a colleague:

| Instead of | Write |
| - | - |
| `LLM AND (weights OR open-source) -rumor` | `new open-weights LLM releases` |
| `pricing` | `pricing change or new plan announcement` |
| `AI news` | One monitor per interest, such as `EU AI Act enforcement` and `Series A rounds in robotics` |

A narrow topic gives fewer, more precise results. Split a broad interest into several monitors.

If you know the sources, name them. `search.include_domains` keeps only pages from the hosts you list, such as `["blog.rust-lang.org"]`. `search.exclude_domains` drops the hosts you don't want.

Every key in your organization sees the same monitors, so reuse one before you create another. Call [List monitors](https://docs.keenable.ai/api-reference/monitors/list.md) with `name` to find a monitor on the same topic. A name is free text that its creator chose, so a monitor on your topic can have another name. Also compare each listed monitor's `search.query` with yours before you create a new one.

## Read the results

This sample lists a monitor's results, newest first, and prints each result's importance, title and URL. The operation is called results everywhere: [List results](https://docs.keenable.ai/api-reference/monitors/results.md) in the API reference, `GET /v1/monitors/{id}/results` as the URL, `monitors.results` in the SDKs and `keenable monitors results` in the CLI. Over MCP, `get_monitor_results` is different: it returns the results this reader hasn't been given yet, across all monitors. The SDK samples need SDK 0.2.0 or newer:

```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 results = await client.monitors.results("mon_3kq9z2c8f1a04b7d9e6f5a21", { limit: 10 });
  for (const result of results.data) {
    console.log(result.importance, result.title, result.url);
  }
}

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()
results = client.monitors.results("mon_3kq9z2c8f1a04b7d9e6f5a21", limit=10)
for result in results.data:
    print(result.importance, result.title, result.url)
```

```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()

	results, err := client.Monitors.Results(context.Background(), "mon_3kq9z2c8f1a04b7d9e6f5a21", &keenable.MonitorResultsParams{Limit: 10})
	if err != nil {
		log.Fatal(err)
	}
	for _, result := range results.Data {
		importance, title := 0, ""
		if result.Importance != nil {
			importance = *result.Importance
		}
		if result.Title != nil {
			title = *result.Title
		}
		fmt.Println(importance, title, result.URL)
	}
}
```

```rust Rust theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::{Client, MonitorResultsParams};

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    // reads KEENABLE_API_KEY from the environment
    let client = Client::new()?;
    let results = client
        .monitors()
        .results(
            "mon_3kq9z2c8f1a04b7d9e6f5a21",
            &MonitorResultsParams { limit: Some(10), ..Default::default() },
        )
        .await?;
    for result in results.data {
        let importance = result.importance.unwrap_or_default();
        let title = result.title.unwrap_or_default();
        println!("{importance} {title} {}", result.url);
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -G https://api.keenable.ai/v1/monitors/mon_3kq9z2c8f1a04b7d9e6f5a21/results \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  --data-urlencode "limit=10"
```

You see one line per result:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
4 Example Labs releases a 70B open-weights model https://example.com/news/example-70b
3 Example-7B weights now on the hub https://example.org/models/example-7b
```

Each result carries the fields of a search result plus what the monitor knows about the page:

| Field | What it holds |
| - | - |
| `summary` | One line on what the page reports. |
| `importance` | How much the page matters for this monitor's topic, from 1 to 5. A monitor doesn't accept pages under 3. Pass `min_importance=4` to keep only the results a reader wouldn't want to miss. |
| `matched_at` | When the monitor accepted the page. Sort and deduplicate on it, not on `published_at`. |
| `published_at`, `published_at_source` | When the page was published, and where that date comes from: `declared`, `url`, `x` or `text`. Keenable checks the page's declared date against its URL and when the crawler first found the page. `published_at` is `null` only in rare cases, such as a changed page that declares no date. |
| `same_story` | How many other pages reported the same story and were left out. A monitor reports each story once, with the first page that carries it. |
| `id` | An opaque ID for this match. The last `id` on a page of results is its `next_cursor`. |

[List results](https://docs.keenable.ai/api-reference/monitors/results.md) covers the monitor's last 500 results. To read a monitor without a webhook or schedule, poll it and stop at the first `id` you've already seen. [Read monitor results](https://docs.keenable.ai/guides/read-monitor-results.md) has a polling loop in every SDK. The API reference lists every field.

A monitor accepts a page only if the page is new: published about a day or less before Keenable crawled it. If Keenable can't establish a page's publish date, the monitor doesn't accept it. The monitor also drops listings, evergreen explainers, filler and pages that only mention the topic.

## Verify a webhook

Every webhook delivery is a `POST` with a JSON body, signed with the monitor's `webhook.secret` under the [Standard Webhooks](https://www.standardwebhooks.com) scheme. Check the signature on the raw request body before you parse it. These handlers verify a delivery with the SDK and print the event type. The TypeScript, Python and Rust handlers need SDK 0.2.0 or later. Until a newer release is out, verify the signature without the SDK, as the steps after the handlers describe:

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

const secret = process.env.KEENABLE_WEBHOOK_SECRET ?? "";
if (!secret) throw new Error("Set KEENABLE_WEBHOOK_SECRET to the monitor's webhook.secret");

export async function POST(request: Request): Promise<Response> {
  const body = await request.text();
  try {
    const event = await verifyWebhook(body, request.headers, secret);
    console.log(event.type);
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response(null, { status: 400 });
    throw err;
  }
}
```

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

from flask import Flask, request
from keenable import WebhookVerificationError, verify_webhook

SECRET = os.environ.get("KEENABLE_WEBHOOK_SECRET", "")
if not SECRET:
    raise SystemExit("Set KEENABLE_WEBHOOK_SECRET to the monitor's webhook.secret")

app = Flask(__name__)


@app.post("/keenable")
def keenable_webhook():
    try:
        event = verify_webhook(request.get_data(), request.headers, SECRET)
    except WebhookVerificationError:
        return "", 400
    print(event.type)
    return "", 204
```

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

import (
	"errors"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"

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

func main() {
	secret, ok := os.LookupEnv("KEENABLE_WEBHOOK_SECRET")
	if !ok || secret == "" {
		log.Fatal("set KEENABLE_WEBHOOK_SECRET to the monitor's webhook.secret")
	}
	http.HandleFunc("/keenable", func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(r.Body)
		if err != nil {
			http.Error(w, "", http.StatusBadRequest)
			return
		}
		event, err := keenable.VerifyWebhook(body, r.Header, secret, nil)
		var refused *keenable.WebhookVerificationError
		if errors.As(err, &refused) {
			http.Error(w, "", http.StatusBadRequest)
			return
		} else if err != nil {
			http.Error(w, "", http.StatusInternalServerError)
			return
		}
		fmt.Println(event.Type)
		w.WriteHeader(http.StatusNoContent)
	})
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

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

use axum::{
    body::Bytes,
    extract::State,
    http::{HeaderMap, StatusCode},
    routing::post,
    Router,
};

async fn keenable_webhook(
    State(secret): State<Arc<str>>,
    headers: HeaderMap,
    body: Bytes,
) -> StatusCode {
    match keenable::verify_webhook(&body, &headers, &secret) {
        Ok(event) => {
            println!("{}", event.event_type);
            StatusCode::NO_CONTENT
        }
        Err(keenable::Error::WebhookVerification(_)) => StatusCode::BAD_REQUEST,
        Err(_) => StatusCode::INTERNAL_SERVER_ERROR,
    }
}

#[tokio::main]
async fn main() {
    let secret = std::env::var("KEENABLE_WEBHOOK_SECRET")
        .ok()
        .filter(|s| !s.is_empty())
        .expect("set KEENABLE_WEBHOOK_SECRET to the monitor's webhook.secret");
    let app = Router::new()
        .route("/keenable", post(keenable_webhook))
        .with_state(Arc::<str>::from(secret));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
```

When a page arrives, your handler prints `monitor.result.found`. A delivery with a wrong signature, or a timestamp more than 5 minutes from now, gets `400`. Each handler stops at startup if `KEENABLE_WEBHOOK_SECRET` is missing or empty, because an empty secret fails every check.

To test a handler locally and debug failed deliveries, see [Receive monitor webhooks](https://docs.keenable.ai/guides/monitor-webhooks.md).

To verify without the SDK:

1. Read three headers: `webhook-id`, `webhook-timestamp` (Unix seconds) and `webhook-signature`.
2. Take the part of the secret after `whsec_` and base64-decode it. That's the key.
3. Compute HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw body>` and base64-encode the result.
4. Compare it, in constant time, with each space-separated `v1,<signature>` entry in `webhook-signature`.
5. Accept the delivery if any entry matches and the timestamp is within 5 minutes of now.

For a complete handler that forwards each page to Slack, see [News monitor to Slack](https://docs.keenable.ai/recipes/news-monitor-to-slack.md).

### Retries

Answer with any `2xx` status within 15 seconds. If a delivery fails, Keenable retries it with backoff, starting at 30 seconds and doubling up to 6 hours, for up to 12 attempts over about 15 hours. A `4xx` other than `408` or `429` isn't retried.

An event keeps its `id`, which is also the `webhook-id` header, across retries, so drop repeats by `id`. Events of one monitor arrive in order. [List deliveries](https://docs.keenable.ai/api-reference/monitors/deliveries.md) shows each event's attempts and last error.

## Webhook events

Every event has the same envelope:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "id": "evt_9f2c4e1a7b3d4c5e8f6a0b1c2d3e4f5a",
  "type": "monitor.result.found",
  "created_at": "2026-11-17T10:42:03.000Z",
  "data": { "monitor_id": "mon_3kq9z2c8f1a04b7d9e6f5a21", "result": { "url": "https://example.com/news/example-70b", "...": "..." } },
  "metadata": { "team": "research" }
}
```

`metadata` is the `metadata` you set on the monitor. [Webhook payload](https://docs.keenable.ai/api-reference/monitors-webhook-payload.md) lists every field of every event type. `data` holds the monitor's ID and one more object, depending on the type:

| Type | `data` holds | Sent when |
| - | - | - |
| `monitor.created`, `monitor.updated`, `monitor.deleted` | `monitor` | The monitor was created, changed or deleted. |
| `monitor.run.created` | `run` | A scheduled or triggered run started. |
| `monitor.run.completed` | `run` | A run finished. A run with no new results still sends it, with `results: []`. |
| `monitor.run.failed` | `run` | A run failed. `run.error` says why. |
| `monitor.disabled` | `monitor`, `reason` | Keenable [disabled](#statuses) the monitor. |
| `monitor.result.found` | `result` | A new page was accepted, minutes after it was crawled. |
| `monitor.result.changed` | `result`, with `change` | A page you already got changed in substance. |

If you leave out `webhook.events`, a monitor sends every type in this table. If you list types, it sends only those. In `monitor.result.found` events, `author` and `image` are always `null`.

## Schedules

A schedule makes a monitor run at set times. Each run returns the results found since the previous run. A schedule is an object with `type`, `value` and, for cron only, `timezone`. [Competitor watch](https://docs.keenable.ai/recipes/competitor-watch.md) uses a weekday cron schedule:

| `type` | `value` | Example | Rules |
| - | - | - | - |
| `cron` | A five-field cron expression | `{"type": "cron", "value": "0 9 * * 1-5", "timezone": "Europe/Paris"}` runs at 9:00 Paris time on weekdays | At most once an hour. `timezone` is an IANA name and defaults to `UTC`. Names such as `mon-fri` and `jan` work. |
| `interval` | A number and a unit: `m`, `h`, `d` or `w` | `{"type": "interval", "value": "6h"}` | From 1 hour to 90 days, counted from when you set the schedule. |
| `once` | An ISO 8601 timestamp or a delay | `{"type": "once", "value": "2026-12-01T12:00:00Z"}` or `{"type": "once", "value": "2h"}` | Up to a year ahead. Leave `value` out to run now. After the run, the monitor's status becomes `completed`. |

Check `upcoming_runs` in the response: it lists the next three run times, in UTC. A schedule that breaks a rule returns `400` with `invalid_request`, and `message` names the rule, for example `a cron schedule may run at most once an hour`. A `timezone` on an `interval` or `once` schedule returns `400` too.

If the monitor misses scheduled times, for example while it's paused, it makes them up with one run that returns everything found since the last run. A monitor without a schedule runs only when you [trigger a run](https://docs.keenable.ai/api-reference/monitors/trigger.md). To change the schedule, send a new one with [Update a monitor](https://docs.keenable.ai/api-reference/monitors/update.md). `"schedule": null` removes it.

### What a run returns

A run returns the results found since the previous run that no earlier run returned, most important first, at most `search.max_results` (10 by default, up to 100). A later run doesn't return results past `max_results`, but [List results](https://docs.keenable.ai/api-reference/monitors/results.md) has all of them. A failed run returns nothing, and its results come with the next run that succeeds.

With `output_schema`, a JSON Schema, each run that finds results also returns `output`: a summary of those results in your schema in `output.structured`, with `grounding` that names the results behind each field.

## Statuses

| Status | Meaning | How it changes |
| - | - | - |
| `active` | The monitor matches new pages and runs on its schedule. | You set it. |
| `paused` | The monitor matches nothing and doesn't run on its schedule. | You set it with `{"status": "paused"}`, and resume with `{"status": "active"}`. |
| `completed` | A `once` monitor after its run. | A new `once` schedule makes it active again. |
| `disabled` | Keenable stopped the monitor after 10 failed runs in a row, or when no webhook delivery succeeded for 3 days. | Fix the cause, then send `{"status": "active"}`. |

When Keenable disables a monitor, it sends `monitor.disabled` with the reason. A paused or completed monitor still answers a triggered run, with the results it found before it stopped. A disabled one returns `409`. To stop a monitor for a while, pause it. [Deleting](https://docs.keenable.ai/api-reference/monitors/delete.md) removes the monitor and its results for good.

## Troubleshooting

| What you see | Why | What to do |
| - | - | - |
| No results right after you create a monitor | A monitor matches only pages crawled after it was created. | Wait. The first results arrive minutes to hours later. Use [Search](https://docs.keenable.ai/products/search.md) for what's already published. |
| A monitor stays quiet for days | Nothing new was published on the topic, or the query is too narrow. | Check the query against [Write a good query](#write-a-good-query). Search for the topic with `published_after` to see whether anything new exists. |
| Too many results, or results off the topic | The query is too broad. | Split it into narrower monitors, or pass `min_importance=4` when you read results. |
| Your webhook gets nothing | Deliveries fail, or `webhook.events` lists types without `monitor.result.found`. | Check [List deliveries](https://docs.keenable.ai/api-reference/monitors/deliveries.md) for the last error. Add `monitor.result.found` to `webhook.events`, or send `"events": []` to go back to every event type, with [Update a monitor](https://docs.keenable.ai/api-reference/monitors/update.md). |
| Every delivery gets `400` from your handler | The handler checks the signature with the wrong secret, or on a parsed body. | Use the `webhook.secret` from the create response, and verify the raw body. |
| The monitor's status is `disabled` | 10 runs failed in a row, or no delivery succeeded for 3 days. | Read the `reason` in the `monitor.disabled` event, fix the cause, then send `{"status": "active"}`. |

## Limits

Monitors is free for now: requests and runs cost nothing.

| Limit | Value |
| - | - |
| Active monitors | 100 per organization. Paused, completed and disabled monitors don't count. The 101st create, or resuming a monitor at the limit, returns `403` with `monitor_limit_reached`. |
| Requests | 120 Monitors API requests per minute per organization, of which at most 10 may create monitors. Over the limit, the API returns `429` with `rate_limited`. |
| Schedule | At most one run an hour. |
| Results | [List results](https://docs.keenable.ai/api-reference/monitors/results.md) covers a monitor's last 500 results. A result's page text, with `search.content.text`, is its first 6,000 characters and is kept for 3 days. |
| Deliveries | [List deliveries](https://docs.keenable.ai/api-reference/monitors/deliveries.md) covers the last 7 days. |
| Metadata | At most 50 keys, all string values. |

Every key in an organization sees the same monitors and shares the request limits, including keys your agents use. If Monitors is turned off for your organization, every call returns `403` with `monitors_not_enabled`. See [Errors](https://docs.keenable.ai/errors.md#monitors-not-enabled).

## Not supported yet

A field the API doesn't have, or doesn't offer yet, returns `400` with `monitor_option_not_supported` and the field's name in `message`. The API never ignores a field. Among them:

* `agent_run_id`, for monitors that rerun an agent.
* `backfill`, for pages from before the monitor existed.
* `memory_scope`.
* Search fields other than `query`, `max_results`, `include_domains`, `exclude_domains` and `content.text`.

A run's `changes` is always `null` for now.

## Next steps

* [News monitor to Slack](https://docs.keenable.ai/recipes/news-monitor-to-slack.md): post each `monitor.result.found` page to a Slack channel.
* [Competitor watch](https://docs.keenable.ai/recipes/competitor-watch.md): a weekday digest of a competitor's own sites, with `output_schema`.
* [Monitors API reference](https://docs.keenable.ai/api-reference/monitors/create.md): every endpoint, field and status code.
* [Monitor guides](https://docs.keenable.ai/guides/create-a-monitor.md): create a monitor, [read its results](https://docs.keenable.ai/guides/read-monitor-results.md) and [receive its webhooks](https://docs.keenable.ai/guides/monitor-webhooks.md).
* [MCP server](https://docs.keenable.ai/mcp-server.md#monitors-tools): create and read monitors from Claude, ChatGPT and other MCP clients.
* [SDKs](https://docs.keenable.ai/sdks.md): install the Python, TypeScript, Go or Rust client.
* [Errors](https://docs.keenable.ai/errors.md): what each code means and how to fix it.

## Related pages

> [card] [Production checklist](https://docs.keenable.ai/production.md)
>
> Ship Keenable search and fetch to production: keys from the environment, rate limits, retries on 429 with Retry-After, stopping on 402, timeouts and status.

> [card] [Get a monitor](https://docs.keenable.ai/api-reference/monitors/get.md)
>
> Get one monitor with GET /v1/monitors/\{id}: its query, status, schedule, webhook and next three run times.

> [card] [List runs](https://docs.keenable.ai/api-reference/monitors/runs.md)
>
> List a monitor's runs with GET /v1/monitors/\{id}/runs, newest first, each with the results it returned.

> [card] [Count monitors](https://docs.keenable.ai/api-reference/monitors/stats.md)
>
> Count your organization's monitors by status and by kind of schedule with GET /v1/monitors/stats.


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