Skip to main content
Create a monitor that watches the web for one topic and hands you the new pages on a schedule you pick. You describe the topic once, limit it to the sources you trust, and get a digest of new results at each run. For what a monitor is and every way to read it, see Monitors. You need an API key. Monitors has no keyless tier. An agent that signed in with AgentID creates its own key. Otherwise a person approves one login: have the agent run keenable login and show you the link and code, then approve it in the console. See Get a key from an agent or the CLI. After that, the agent uses the saved key without you.

Request fields

A create request is a JSON body sent to POST /v1/monitors. Only search.query is required:

Create a scheduled monitor

This sample creates a monitor for EU AI Act enforcement news from two sites. It runs at 9:00 Paris time on weekdays, returns up to 20 results per run, and carries a team tag. It prints the monitor’s ID, its status and its next three run times:
The SDK tabs need SDK 0.2.0 or later, the first version with Monitors. If your package manager doesn’t offer 0.2.0 yet, use the curl tab. You see the ID, active and three run times in UTC. 9:00 in Paris is 08:00 UTC in winter:
Example output
The create call takes a few seconds. The monitor starts empty and matches only pages crawled after you create it. Each run returns the results found since the previous run. To read them, see Read monitor results.

Check that a new monitor works

A new monitor has no results for minutes to hours, so an empty list doesn’t mean it is broken. To confirm the setup right away:
  1. Check that the create response has status: "active" and a list of upcoming_runs. If the schedule was refused, the API returns 400 instead.
  2. Trigger a run and read it with Get a run. A run that found nothing new still completes, with no results.
  3. If the monitor has a webhook, send it a signed sample event. See Test your handler locally.
Then come back for results after the monitor has had time to match new pages.

Reuse a monitor before you create one

Every API key in your organization sees the same monitors. Before you create a monitor, list the ones whose name contains your topic. This request returns active monitors with AI Act in their name:
You get {"data": [...], "has_more": false, "next_cursor": null}. If data holds a monitor on your topic, use its id instead of creating another. To find monitors by tag, pass metadata[team]=policy instead of name. See List monitors.

Retry a create safely

A create can time out after the monitor was made. Send the same Idempotency-Key header when you retry, so the retry returns the first monitor instead of creating a second one: Pick one key per monitor you mean to create, such as eu-ai-act-enforcement-v1. The SDKs send the key from idempotency_key (idempotencyKey in TypeScript, IdempotencyKey in Go).

Change a monitor after you create it

Send only the fields that change to Update a monitor. The API merges search and webhook into the stored values. This request moves the run to 7:00 Paris time and keeps the query and sites:
The response is the monitor with new upcoming_runs. To stop runs without losing results, send {"status": "paused"}. {"schedule": null} removes the schedule, and the monitor then runs only when you trigger a run.

Common mistakes

API reference