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.
List incidents
Section titled “List incidents”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.
Get an incident
Section titled “Get an incident”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):
# equivalent to the numeric form abovecurl 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.”
Incident types
Section titled “Incident types”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.
Your first monitor takes 30 seconds.
Sign in with GitHub, Google, Microsoft, or email, and your first check runs right away. 50 monitors, free, no card.