Skip to main content
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. 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. 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 installed and keenable login done, this command creates a monitor that runs once a day:
The CLI prints the new monitor with its id. Later, read its results, keeping only the important ones:
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 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. To test get_monitor_results with curl, see 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. 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: You see the new monitor’s ID, active and the secret:
Example output
Only two responses carry webhook.secret: the create response, and the response to an update 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 for what’s already published. For a monitor with a schedule, chosen sources and metadata, see Create a monitor. 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: 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 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 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:
You see one line per result:
Example output · results vary
Each result carries the fields of a search result plus what the monitor knows about the page: List results 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 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 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:
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. 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.

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 shows each event’s attempts and last error.

Webhook events

Every event has the same envelope:
metadata is the metadata you set on the monitor. Webhook payload lists every field of every event type. data holds the monitor’s ID and one more object, depending on the type: 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 uses a weekday cron schedule: 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. To change the schedule, send a new one with Update a monitor. "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 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

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 removes the monitor and its results for good.

Troubleshooting

Limits

Monitors is free for now: requests and runs cost nothing. 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.

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

Production checklist

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.

Get a monitor

Get one monitor with GET /v1/monitors/{id}: its query, status, schedule, webhook and next three run times.

List runs

List a monitor’s runs with GET /v1/monitors/{id}/runs, newest first, each with the results it returned.

Count monitors

Count your organization’s monitors by status and by kind of schedule with GET /v1/monitors/stats.