Reference

REST API — Monitors

Create, update, delete, pause, and query Drumbeats monitors via the REST API. Includes ping history, payload retrieval, and event-driven warnings.

The Drumbeats Monitors API creates, updates, deletes, pauses, and queries monitors. Each endpoint requires an X-API-Key header — see the REST API overview for authentication and scoping rules.

Monitor writes (create, update, delete, pause, resume) require the manage_monitors permission scope on top of the project-role gate listed per operation below. Project-scoped keys carry monitor-write access by default, so this is unchanged for them; account-scoped keys must have been minted with manage_monitors selected.

List monitors

GET /v1/monitors?project_id=<project-id>

GET /v1/monitors?project_id=<project-id>

Returns every monitor inside the given project.

Parameter	Required	Type	Description
`project_id`	Yes	UUID	Project whose monitors to list.

curl "https://api.drumbeats.io/v1/monitors?project_id=<project-id>" \
  -H "X-API-Key: dk_live_<key>"

curl "https://api.drumbeats.io/v1/monitors?project_id=<project-id>" \
  -H "X-API-Key: dk_live_<key>"

Response shape:

{
  "monitors": [
    {
      "id": "<monitor-uuid>",
      "project_id": "<project-uuid>",
      "slug": "daily-backup",
      "name": "Daily Backup Job",
      "description": "Nightly database backup",
      "tags": ["database", "backup"],
      "type": "JOB_CRON",
      "schedule": "0 2 * * *",
      "timezone": "UTC",
      "grace_period_seconds": 300,
      "schedule_tolerance": 1,
      "failure_tolerance": 1,
      "min_duration_seconds": 60,
      "max_duration_seconds": 300,
      "alert_enabled": true,
      "alert_surge_threshold": 10,
      "alerts_paused_until": null,
      "retention_count": 200,
      "notification_group_ids": [],
      "status": "UP",
      "consecutive_failures": 0,
      "consecutive_misses": 0,
      "consecutive_alerts": 0,
      "last_success_at": "2026-05-10T02:00:00.000Z",
      "next_expected_at": "2026-05-11T02:00:00.000Z",
      "created_at": "2026-04-15T12:00:00.000Z",
      "updated_at": "2026-05-10T02:00:00.000Z"
    }
  ]
}

{
  "monitors": [
    {
      "id": "<monitor-uuid>",
      "project_id": "<project-uuid>",
      "slug": "daily-backup",
      "name": "Daily Backup Job",
      "description": "Nightly database backup",
      "tags": ["database", "backup"],
      "type": "JOB_CRON",
      "schedule": "0 2 * * *",
      "timezone": "UTC",
      "grace_period_seconds": 300,
      "schedule_tolerance": 1,
      "failure_tolerance": 1,
      "min_duration_seconds": 60,
      "max_duration_seconds": 300,
      "alert_enabled": true,
      "alert_surge_threshold": 10,
      "alerts_paused_until": null,
      "retention_count": 200,
      "notification_group_ids": [],
      "status": "UP",
      "consecutive_failures": 0,
      "consecutive_misses": 0,
      "consecutive_alerts": 0,
      "last_success_at": "2026-05-10T02:00:00.000Z",
      "next_expected_at": "2026-05-11T02:00:00.000Z",
      "created_at": "2026-04-15T12:00:00.000Z",
      "updated_at": "2026-05-10T02:00:00.000Z"
    }
  ]
}

Get a monitor

GET /v1/monitors/<monitor-id>

GET /v1/monitors/<monitor-id>

Returns a single monitor by UUID.

curl https://api.drumbeats.io/v1/monitors/<monitor-id> \
  -H "X-API-Key: dk_live_<key>"

curl https://api.drumbeats.io/v1/monitors/<monitor-id> \
  -H "X-API-Key: dk_live_<key>"

Response: { "monitor": { … } } with the same shape as the list endpoint.

Create a monitor

POST /v1/monitors

POST /v1/monitors

Required role: Member or higher.

Field	Required	Type	Description
`project_id`	Yes	UUID	Project to create the monitor in.
`name`	Yes	string	Display name.
`type`	Yes	string	`JOB_CRON`, `JOB_HEARTBEAT`, or `JOB_BASIC` (event-driven). See Monitor types.
`schedule`	Required for Cron / Heartbeat	string	Cron expression for `JOB_CRON`, interval string (`5m`, `1h`) for `JOB_HEARTBEAT`.
`timezone`	No	string	IANA timezone (default `UTC`). Applies to cron schedules.
`slug`	No	string	Human-readable URL identifier. Used by the project-slug Ping API form.
`grace_period_seconds`	No	integer	Seconds to wait past `next_expected_at` before opening a `MISSED` incident. Default `300`.
`schedule_tolerance`	No	integer	Consecutive misses required before alerting. Default `1`.
`failure_tolerance`	No	integer	Consecutive failures required before alerting. Default `1`.
`min_duration_seconds`	No	integer	Floor for `DURATION_LOW` detection.
`max_duration_seconds`	No	integer	Ceiling for `DURATION_HIGH` detection and hung-run detection.
`alert_enabled`	No	boolean	Toggle alerts entirely. Default `true`.
`alert_surge_threshold`	No	integer	Max alerts per surge window. Default `10`.
`retention_count`	No	integer	Number of pings to retain. Default `200`.
`notification_group_ids`	No	UUID[]	Notification groups to page on incidents.

curl -X POST https://api.drumbeats.io/v1/monitors \
  -H "X-API-Key: dk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project-id>",
    "name": "Nightly Backup",
    "slug": "nightly-backup",
    "type": "JOB_HEARTBEAT",
    "schedule": "5m",
    "timezone": "UTC",
    "grace_period_seconds": 300
  }'

curl -X POST https://api.drumbeats.io/v1/monitors \
  -H "X-API-Key: dk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project-id>",
    "name": "Nightly Backup",
    "slug": "nightly-backup",
    "type": "JOB_HEARTBEAT",
    "schedule": "5m",
    "timezone": "UTC",
    "grace_period_seconds": 300
  }'

Returns 201 with { "message": "Monitor created successfully", "monitor": { … } }.

Update a monitor

Required role: Manager or higher. Send only the fields you want to change.

Delete a monitor

Required role: Manager or higher. Hard-deletes the monitor and its ping history.

Pause / resume a monitor

Pausing accepts incoming pings but does not evaluate them — no incidents open, no alerts fire. Use this for planned maintenance.

Ping history

Returns paginated ping history. Useful for replay, debugging, and exporting.

Parameter	Type	Default	Description
`page`	integer	1	Page number.
`limit`	integer	20	Items per page (max 100).
`event`	string	—	Filter to `START`, `SUCCESS`, `FAILURE`, or `LOG`.
`run_id`	string	—	Filter to one execution (event-driven).
`exit_code`	integer	—	Filter by exit code.
`duration_assertion`	string	—	Filter to `PASS`, `TOO_FAST`, or `TOO_SLOW`.
`from_date`	ISO datetime	—	Start of date range.
`to_date`	ISO datetime	—	End of date range.

Response:

Note: payload is null on the list endpoint when the payload exceeds 10 KB. Fetch it explicitly via the next endpoint.

Get a ping's full payload

Returns the full payload — including payloads spilled to object storage.

Get monitor incidents

Returns incidents specific to one monitor. For cross-monitor incident queries, use the project-scoped Incidents API directly.

Get monitor warnings

Returns advisory warnings about the monitor's configuration — missing run_id, missing start pings on Event-driven monitors, and similar. Analyzes the last 7 days, up to 50 pings.

REST API overview — auth, pagination, errors.
Monitor types — what type values mean and how each behaves.
Ping API — the surface that produces the pings these endpoints query.
Incidents — how the consecutive_failures / consecutive_misses counters drive incident creation.