Manage monitors via the API

Monitors watch a query’s result on a schedule and notify destinations when a condition is met. This covers the lifecycle end to end.

1. Create a destination to notify

POST /api/destinations
{ "name": "#alerts", "type": "slack", "options": { "url": "https://hooks.slack.com/..." } }

Requires manage_destinations. See the Destinations reference — GET /api/destinations/types lists every supported type and its configuration fields.

2. Create the monitor

POST /api/monitors
{ "query_id": 42, "name": "Signup drop", "options": { "column": "count", "op": "<", "value": 10 }, "rearm": 3600 }

options.column is the result column being checked, op is one of >, <, >=, <=, ==, !=, and value is the threshold; rearm (seconds) is how long the monitor waits before re-triggering after it’s already fired. See the Monitors reference.

3. Subscribe the destination

POST /api/monitors/{id}/subscriptions
{ "destination_id": 4 }

A monitor with no subscriptions checks its condition but never notifies anyone.

4. Attach a schedule

Monitors don’t check themselves — attach a recurring schedule the same way you would for a query:

POST /api/schedules
{ "entity_type": "monitor", "entity_id": 15, "spec": { "type": "cron", "cron": "0 */15 * * * *" }, "timezone": "UTC" }

A cron expression here is 6 fields (seconds first) — a standard 5-field crontab expression is rejected.

See the Schedules reference.

5. Run it manually

POST /api/monitors/{id}/run

Checks the condition immediately through the runs pipeline, independent of the schedule. Returns 201 if a new run started, 200 if one was already in flight. The run shows up in GET /api/runs?entity_type=monitor&entity_id={id} — see the Runs reference.

6. Acknowledge, snooze, or mute an active alert

POST /api/monitors/{id}/ack      # acknowledge the current trigger
POST /api/monitors/{id}/snooze   # { "minutes": 60 } — suppress notifications for a window
POST /api/monitors/{id}/mute     # suppress until explicitly unmuted

See the Monitors reference for the full set, including /unmute.

7. Review delivery history

GET /api/monitors/{id}/deliveries

Newest-first, capped at 50 rows — each row’s state/status/error tells you whether a notification actually reached the destination. See the Monitors reference.