---
title: "Incidents"
description: "Query the per-account incident log (30-day user-visible retention)."
doc_version: "1"
last_updated: "2026-11-19"
---

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

```bash
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:

```json
{
  "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](/docs/guides/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

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

The response wraps the incident under an `incident` key:

```json
{
  "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`):

```bash
# 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."

## 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.