---
title: "Incidents"
description: "Query the per-account incident log (30-day retention)."
doc_version: "1"
last_updated: "2026-06-02"
---

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.

Retention is **30 days** — incidents older than that are dropped from the table. For longer history, capture incidents to your own store via webhooks.

## List incidents

```bash
curl https://api.uptimemonitoring.com/api/v1/incidents \
  -H "Authorization: Bearer $UPTIMEMONITORING_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,
      "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"
    }
  ],
  "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. `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.uptimemonitoring.com/api/v1/incidents/4422 \
  -H "Authorization: Bearer $UPTIMEMONITORING_API_KEY"
```

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

```json
{
  "incident": {
    "id": 4422,
    "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"
  }
}
```

A non-numeric ID returns `400 invalid incident ID`. A numeric-but-missing ID returns `404 incident not found`.

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