Monitors
Create a monitor
Create a monitor with POST /v1/monitors: a topic, an optional schedule and webhook. The response carries the webhook signing secret.
POST
TypeScript
Start watching the web for new pages about a topic. Store
webhook.secret from the response. Only this response and an update that adds a first webhook carry it. Send an Idempotency-Key header so a retried create doesn’t make a second monitor. See Monitors for schedules, events and signatures.
When to use it
Create one monitor per topic. Every key in your organization sees the same monitors, so first list your monitors withname and reuse one on the same topic. Write search.query as a topic in plain words, not keywords. Write a good query has examples.
A new monitor starts empty and doesn’t backfill: it matches only pages crawled after you create it. For pages already published, use Search. A create counts toward your organization’s active monitors. See Limits.
The same Idempotency-Key with the same body within 24 hours returns the monitor the first call created. The same key with another body returns 409 with idempotency_conflict.
SDK, CLI and MCP
The SDK methods need SDK 0.2.0 or later. Each SDK sends an
Idempotency-Key on every create, yours or a new one, so it can retry the call safely. See SDKs → Monitors, CLI → Monitors and Monitors tools.
Related operations
- Update a monitor changes the query, schedule or webhook later.
- Run a monitor now starts a run without waiting for the schedule.
- List results reads every result the monitor accepted.
Authorizations
Headers
Body
application/json
Response
The new monitor, with webhook.secret when you sent a webhook