Skip to main content
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: 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.

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:
You see the new monitor’s ID, active and the secret:
Example output
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 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:
You see one line per page:
Example output · results vary
Each page carries the fields of a search result plus what the monitor knows about it: List pages 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 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:
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 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. data holds the monitor’s ID and one more object, depending on the type: 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: 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.

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

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

Limits

Monitors is free for now: requests and runs draw no credits. 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.

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: every endpoint, field and status code.
  • MCP server: create and read monitors from Claude, ChatGPT and other MCP clients.
  • SDKs: install the Python, TypeScript, Go or Rust client.
  • Errors: what each code means and how to fix it.