Skip to content

Incidents

Down events and flap events are recorded as incidents. A monitor that goes down opens a down incident, which closes by setting resolved_at when the monitor recovers — recovery does NOT spawn a separate row. Flap events open a flapping incident that resolves the same way.

The API exposes a queryable log so you can build status pages, post-mortem timelines, or pipe incidents into your own alerting.

This endpoint’s user-visible promise is 30 days — list_incidents/get_incident don’t return anything older than that, by design. The underlying rows physically persist longer (95 days) so the report-email worker and status pages have enough lookback, but that longer window isn’t something you can query here; for anything past 30 days, capture incidents to your own store via webhooks as they happen.

Terminal window
curl https://api.monitive.com/api/v1/incidents \
-H "Authorization: Bearer $MONITIVE_API_KEY"

Ordered newest first. Supports filtering and pagination via query parameters:

Parameter Type Description
monitor_id integer Restrict to incidents for one monitor.
type string down or flapping.
started_after RFC3339 datetime Only incidents started strictly after this time.
started_before RFC3339 datetime Only incidents started strictly before this time.
limit integer (1–100) Page size. Default 50. Out-of-range values return 400 limit must be between 1 and 100.
offset integer Skip the first N results. Default 0.

Response shape:

{
"incidents": [
{
"id": 4422,
"number": 7,
"ref": "k7q2mx-7",
"monitor_ref": "k7q2mx-14",
"monitor_id": 1287,
"account_id": 14,
"type": "down",
"started_at": "2026-05-07T09:14:02Z",
"resolved_at": "2026-05-07T09:18:51Z",
"evidence": [
{
"region": "EU",
"timestamp": "2026-05-07T09:14:01Z",
"status_code": 503,
"ttfb_ms": 2143
},
{
"region": "US",
"timestamp": "2026-05-07T09:14:00Z",
"status_code": 503,
"ttfb_ms": 2087
}
],
"created_at": "2026-05-07T09:14:02Z",
"maintenance": false
}
],
"total": 1,
"limit": 50,
"offset": 0
}

resolved_at is absent (the key is omitted from the JSON object) while the incident is still ongoing; it appears once the monitor recovers. maintenance is always present as true or false — never omitted — and is set once, when the incident opens: true if the monitor’s maintenance window was active at that instant, false otherwise (including for every incident on a monitor with no maintenance window configured). See Maintenance windows for how this flag interacts with alert delivery. total reports the count of incidents matching the supplied filters (monitor_id, type, started_after, started_before) — paginate against this number, not the entire 30-day window.

Terminal window
curl https://api.monitive.com/api/v1/incidents/4422 \
-H "Authorization: Bearer $MONITIVE_API_KEY"

The response wraps the incident under an incident key:

{
"incident": {
"id": 4422,
"number": 7,
"ref": "k7q2mx-7",
"monitor_ref": "k7q2mx-14",
"monitor_id": 1287,
"account_id": 14,
"type": "down",
"started_at": "2026-05-07T09:14:02Z",
"resolved_at": "2026-05-07T09:18:51Z",
"evidence": [],
"created_at": "2026-05-07T09:14:02Z",
"maintenance": false
}
}

{incidentID} takes either a numeric id or a ref (<account handle>-<number>, e.g. k7q2mx-7):

Terminal window
# equivalent to the numeric form above
curl https://api.monitive.com/api/v1/incidents/k7q2mx-7 \
-H "Authorization: Bearer $MONITIVE_API_KEY"

A value that’s neither a numeric id nor a well-formed ref returns 400 invalid incident ID. A missing id, or a ref that doesn’t resolve or belongs to another account, returns 404 incident not found — the same body in both cases, so a caller can’t distinguish “wrong account’s ref” from “no such id.”

type Meaning
down Monitor transitioned from up to down. Resolves when it transitions back to up.
flapping Monitor crossed the flap threshold (more than 10 transitions per hour). Resolves when traffic stabilises.

The up type is reserved for future use and is not currently emitted.