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 andkeenable login done, this command creates a monitor that runs once a day:
id. Later, read its results, keeping only the important ones:
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 amonitor.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
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:
Example output · results vary
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 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. 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:
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:
- Read three headers:
webhook-id,webhook-timestamp(Unix seconds) andwebhook-signature. - Take the part of the secret after
whsec_and base64-decode it. That’s the key. - Compute HMAC-SHA256 over
<webhook-id>.<webhook-timestamp>.<raw body>and base64-encode the result. - Compare it, in constant time, with each space-separated
v1,<signature>entry inwebhook-signature. - Accept the delivery if any entry matches and the timestamp is within 5 minutes of now.
Retries
Answer with any2xx 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 withtype, 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 mostsearch.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, returns400 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_domainsandcontent.text.
changes is always null for now.
Next steps
- News monitor to Slack: post each
monitor.result.foundpage to a Slack channel. - Competitor watch: a weekday digest of a competitor’s own sites, with
output_schema. - Monitors API reference: every endpoint, field and status code.
- Monitor guides: create a monitor, read its results and receive its webhooks.
- 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.
Related pages
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.