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 amonitor.hit event. It prints the monitor’s ID, its status and the webhook’s signing secret:
active and the secret:
Example output
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:Example output · results vary
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 aPOST 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:
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 withtype, 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 mostsearch.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, returns400 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’schanges.backfill, for pages from before the monitor existed.memory_scope.- Search fields other than
query,max_results,include_domains,exclude_domainsandcontent.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.