> ## 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
> 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
> Read an API key from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat; send them to https://docs.keenable.ai/api-keys.md
> 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.
> Every error, with its cause and fix: https://docs.keenable.ai/errors.md

# Monitors

> A monitor watches the web for new pages about a topic and sends them to your webhook, returns them in scheduled runs, or lists them for you to poll. Free for now, up to 100 active monitors per organization. Quickstart, schedules, webhook events and signatures, and limits.

A monitor is a saved search that returns only what's new. You describe a topic once. Keenable checks every page it crawls against your monitors and keeps the pages that report something new about the topic. You get those pages in one or more of three ways:

| Way | What you get | Set it up with |
| - | - | - |
| Instant webhook events | Each new page, minutes after it's crawled | A `webhook` that lists `monitor.hit` |
| Runs | The pages found since the previous run, on a schedule or when you ask | A `schedule`, or [Run a monitor now](https://docs.keenable.ai/api-reference/monitors/trigger.md) |
| Polling | Every page the monitor accepted, newest first | [List pages](https://docs.keenable.ai/api-reference/monitors/pages.md) |

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.

## Create a monitor

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

```typescript TypeScript theme={"system"}
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.hit", "monitor.disabled"],
    },
  });
  console.log(monitor.id, monitor.status);
  console.log(monitor.webhook?.secret); // only the create response carries it
}

main();
```

```python Python theme={"system"}
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.hit", "monitor.disabled"],
    },
)
print(monitor.id, monitor.status)
print(monitor.webhook.secret)  # only the create response carries it
```

```go Go theme={"system"}
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.hit", "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) // only the create response carries it
	}
}
```

```rust Rust theme={"system"}
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.hit".into(), "monitor.disabled".into()]),
            }),
            ..Default::default()
        })
        .await?;
    println!("{} {}", monitor.id, monitor.status);
    if let Some(webhook) = monitor.webhook {
        println!("{}", webhook.secret.unwrap_or_default()); // only the create response carries it
    }
    Ok(())
}
```

```bash curl theme={"system"}
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.hit", "monitor.disabled"]
    }
  }'
```

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

```text Example output theme={"system"}
mon_3kq9z2c8f1a04b7d9e6f5a21 active
whsec_example
```

Store `webhook.secret` where your webhook handler can read it. The create response is the only one that carries it.

Creating a monitor takes a few seconds. The monitor starts empty: it matches pages crawled after you create it, so the first pages 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.

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`.

## Read the pages

This sample lists the pages a monitor accepted, newest first, and prints each page's importance, title and URL:

```typescript TypeScript theme={"system"}
import { Keenable } from "keenable";

async function main() {
  // reads KEENABLE_API_KEY from the environment
  const client = new Keenable();
  const pages = await client.monitors.pages("mon_3kq9z2c8f1a04b7d9e6f5a21", { limit: 10 });
  for (const page of pages.data) {
    console.log(page.importance, page.title, page.url);
  }
}

main();
```

```python Python theme={"system"}
from keenable import Keenable

# reads KEENABLE_API_KEY from the environment
client = Keenable()
pages = client.monitors.pages("mon_3kq9z2c8f1a04b7d9e6f5a21", limit=10)
for page in pages.data:
    print(page.importance, page.title, page.url)
```

```go Go theme={"system"}
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()

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

```rust Rust theme={"system"}
use keenable::{Client, MonitorPagesParams};

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

```bash curl theme={"system"}
curl -G https://api.keenable.ai/v1/monitors/mon_3kq9z2c8f1a04b7d9e6f5a21/hits \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  --data-urlencode "limit=10"
```

You see one line per page:

```text Example output · results vary theme={"system"}
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 page carries the fields of a search result plus what the monitor knows about it:

| 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 pages 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 pages](https://docs.keenable.ai/api-reference/monitors/pages.md) covers the monitor's last 500 pages. To read a monitor without a webhook or schedule, poll pages and stop at the first `id` you've already seen. 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. A page whose publish date can't be established isn't accepted. Listings, evergreen explainers, filler and pages that only mention the topic are dropped too. A quiet monitor usually means nothing new was published.

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

```typescript TypeScript theme={"system"}
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={"system"}
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={"system"}
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={"system"}
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.hit`. A delivery with a wrong signature, or a timestamp more than 5 minutes from now, gets `400`. Each handler stops at startup when `KEENABLE_WEBHOOK_SECRET` is missing or empty, because an empty secret fails every check.

To verify without the SDK, read three headers: `webhook-id`, `webhook-timestamp` (Unix seconds) and `webhook-signature`. Compute HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw body>`. The key is the part of the secret after `whsec_`, base64-decoded. Base64-encode the result and compare it, in constant time, with each space-separated `v1,<signature>` entry in `webhook-signature`. Accept the delivery if any entry matches and the timestamp is within 5 minutes of now.

Answer with any `2xx` status within 15 seconds. A failed delivery is retried 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={"system"}
{
  "id": "evt_9f2c4e1a7b3d4c5e8f6a0b1c2d3e4f5a",
  "type": "monitor.hit",
  "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. `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 pages 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.hit` | `result` | A new page was accepted, minutes after it was crawled. |
| `monitor.update` | `result`, with `change` | A page you already got changed in substance. |

If `webhook.events` is left out, a monitor sends the first seven types. It sends `monitor.hit` and `monitor.update` only when `webhook.events` lists them, and then it sends only the types listed. In `monitor.hit` events, `author` and `image` are always `null`.

## Schedules

A schedule makes a monitor run at set times. Each run returns the pages found since the previous run. A schedule is an object with `type`, `value` and, for cron only, `timezone`:

| `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.

## Runs and pages

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

With `output_schema`, a JSON Schema, each run that finds pages also returns `output`: a summary of those pages in your schema in `output.structured`, with `grounding` that names the pages 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 pages 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 pages for good.

## Limits

Monitors is free for now: requests and runs draw no [credits](https://docs.keenable.ai/credits.md).

| 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. |
| Pages | [List pages](https://docs.keenable.ai/api-reference/monitors/pages.md) covers a monitor's last 500 pages. 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. 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. These fields are in the monitor object so its shape won't change later:

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

`estimated_cost_usd`, `cost_this_month_usd` and a run's `usage` are always `null` while monitors are free. A result's `favicon` and `highlights` are always `null`.

## Next steps

* [Monitors API reference](https://docs.keenable.ai/api-reference/monitors/create.md): every endpoint, field and status code.
* [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.


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