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 toPOST /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 ateam tag. It prints the monitor’s ID, its status and its next three run times:
active and three run times in UTC. 9:00 in Paris is 08:00 UTC in winter:
Example output
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:- Check that the create response has
status: "active"and a list ofupcoming_runs. If the schedule was refused, the API returns400instead. - Trigger a run and read it with Get a run. A run that found nothing new still completes, with no results.
- If the monitor has a webhook, send it a signed sample event. See Test your handler locally.
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 withAI Act in their name:
{"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 sameIdempotency-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 mergessearch and webhook into the stored values. This request moves the run to 7:00 Paris time and keeps the query and sites:
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
- Create a monitor: every field and status code.
- Get a monitor: check
upcoming_runsand the stored schedule. - Read monitor results: poll results, read runs or let your agent read them.
- Receive monitor webhooks: get each new page at your endpoint.