Skip to main content
POST
Use exactly one Search target, or 1 to 10 Page targets with distinct URLs. Do not mix Search and Page targets in one monitor. The monitor starts as active; its first run becomes due immediately and starts asynchronously. goal is optional and separate from the Search query. To retrieve results without notifications, omit webhook or set it to null; runs and their changes remain available through the API.

Webhook secrets and retries

When you configure a webhook without a secret, the service generates one and returns it in webhook.secret only in the response that generated it. Store it to verify deliveries. A secret you supply is never returned. Use an Idempotency-Key header when retrying the original create request. Reusing the key returns the original monitor in its current state, even after an update, without its secret. Using the same key for a different create request returns 400. If the first response was lost, set a new secret with Update a monitor. Creating a monitor at your API organization’s active-monitor cap returns HTTP 409 with quota_exceeded. Pause or delete an active monitor, or upgrade the organization’s tier, before retrying.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Unique key for this create. A repeat with the same key and the same body returns the monitor that the first request created, in its current state and without the secret; the same key with a different body is a 400.

Maximum string length: 200

Body

application/json
name
string
required
Required string length: 1 - 256
targets
object[]
required

Exactly one search target, or 1 to 10 page targets with distinct URLs

Required array length: 1 - 10 elements
schedule
object
required
goal
string

What counts as worth an alert; each candidate is judged against it

Maximum string length: 2000
webhook
object | null

Optional delivery endpoint; omitted or null sends no events

metadata
object

Up to 16 key value pairs; keys 1 to 64 characters, values up to 512 characters (Unicode code points, valid UTF-8). Echoed on every webhook.

Response

The created monitor, with webhook.secret if the service generated it

Fields that do not apply are omitted, never null: webhook, pause_reason, current_run_id, next_run_at and last_run.

id
string
required

Opaque ID with the prefix mon_

Maximum string length: 64
object
enum<string>
required
Available options:
monitor
name
string
required
goal
string
required

"" when unset

targets
object[]
required

One thing a monitor watches. Today a monitor has exactly one search target, or 1 to 10 page targets with distinct URLs. New types may be added; skip targets with an unknown type.

schedule
object
required

When a monitor runs. New types may be added.

metadata
object
required

Up to 16 key value pairs; keys 1 to 64 characters, values up to 512 characters (Unicode code points, valid UTF-8). Echoed on every webhook.

status
enum<string>
required

active monitors run on their schedule; paused ones don't run until resumed. Whether a run is in flight is current_run_id, not the status. New statuses may be added; treat an unknown one as not running on its schedule.

Available options:
active,
paused
created_at
string<date-time>
required

RFC 3339 in UTC with whole seconds, for example 2026-11-12T09:00:41Z.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
updated_at
string<date-time>
required

RFC 3339 in UTC with whole seconds, for example 2026-11-12T09:00:41Z.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
webhook
object
pause_reason
enum<string>

Only while paused

Available options:
user,
insufficient_credits,
org_policy,
webhook_failing,
source_failing
current_run_id
string

The queued or running run

next_run_at
string<date-time>

Omitted while paused

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
last_run
object

The last finished run