Alerts

An alert is fired by a monitor state transition or by the Events API. Alerts flow through the escalation policy you assigned to the monitor; each step fans out to notification channels.

Endpoints

Method	Path	Description	Scope
`GET`	`/api/v1/alerts`	List alerts.	`alerts`
`GET`	`/api/v1/alerts/{id}`	Read one.	`alerts`
`POST`	`/api/v1/alerts/{id}/ack`	Acknowledge.	`alerts`
`POST`	`/api/v1/alerts/{id}/resolve`	Resolve.	`alerts`
`GET`	`/api/v1/alerts/{id}/timeline`	Timeline events (state changes, acks, notifies).	`alerts`
`POST`	`/api/v1/alerts/{id}/create-incident`	Promote an alert into an incident.	`incidents`

List alerts

GET /api/v1/alerts

Query parameters:

Parameter	Description
`status`	`firing`, `acknowledged`, `resolved`. Comma-separated for multiple.
`severity`	`info`, `warning`, `critical`.
`monitor_id`	Filter by originating monitor.
`group_id`	Filter by originating monitor group.
`from`, `to`	ISO timestamps; filter by `fired_at`.
`q`	Search over summary + reason.
`sort`	`fired_at`, `severity`. `-fired_at` default.
`limit`, `cursor`	Pagination.

Alert document

{
  "id": "01HXABCFIREDBBBBBBBB",
  "monitor_id": "01HXABCMONITOR0000",
  "monitor_name": "Public API",
  "severity": "critical",
  "status": "firing",
  "summary": "Public API is down",
  "reason": "503 from /health for 3 consecutive checks",
  "fired_at": "2026-04-24T17:42:03.417Z",
  "acknowledged_at": null,
  "acknowledged_by": null,
  "resolved_at": null,
  "current_escalation_step": "01HXABCSTEP0000",
  "notification_count": 3,
  "labels": { "env": "prod", "team": "platform" }
}

Acknowledge

POST /api/v1/alerts/{id}/ack

{ "note": "Investigating; pager acknowledged." }

Idempotent: acking an already-acked alert returns 200 with already_acknowledged: true.
The caller is recorded as acknowledged_by. For API-key calls, acknowledged_by is the key’s owning user or key:{key_id} if the key is service-bound.

Resolve

POST /api/v1/alerts/{id}/resolve

{ "note": "Rolled back the bad deploy." }

Auto-resolve: monitors return up → alerts resolve automatically after the freshness window (60 s default).
Manual resolve wins over auto. You can resolve a still-firing monitor’s alert if you choose.

Timeline

GET /api/v1/alerts/{id}/timeline returns an ordered list of events:

{
  "data": [
    { "type": "fired", "at": "2026-04-24T17:42:03Z", "reason": "503 from /health …" },
    { "type": "notification_sent", "at": "2026-04-24T17:42:04Z", "channel": "slack:#oncall" },
    { "type": "escalated", "at": "2026-04-24T17:47:03Z", "from_step": "…", "to_step": "…" },
    { "type": "acknowledged", "at": "2026-04-24T17:48:10Z", "by": "usr_alice", "note": "…" }
  ]
}

Escalation Policies: how alerts fan out.
Incidents: customer-facing incident records.
Knative Eventing → Bidirectional Alerts: reply-based ack/resolve from external systems.