---
title: "List Incidents"
method: GET
path: "/v1/incidents"
tags: ["Incidents"]
---

# List Incidents

`GET /v1/incidents`

## Request

- Base URL: `https://api.fettle.sh` (the document declares no server; this is the origin it was published from)
- URL: `https://api.fettle.sh/v1/incidents`
- Auth: API key in header `Authorization`

List incidents across the active organization's monitors, filtered by status, cause, period.

## Query parameters

- `monitor_id` string, uuid, nullable
- `status` 'open' | 'resolved': Status filter accepted by the incidents listing endpoint. ``OPEN`` keeps only ongoing incidents (``resolved_at IS NULL``); ``RESOLVED`` keeps only closed ones. Omitting the filter returns both.
- `cause` 'TIMEOUT' | 'DNS_FAILURE' | 'CONNECTION_REFUSED' | 'TLS_INVALID' | 'HTTP_4XX' | 'HTTP_5XX' | 'HTTP_UNEXPECTED_STATUS' | 'KEYWORD_MISSING' | 'TOO_MANY_REDIRECTS' | 'TARGET_BLOCKED' | 'PORT_STATE_MISMATCH' | 'INVALID_TARGET' | 'HEARTBEAT_MISSED' | 'HEARTBEAT_FAILED' | 'UNKNOWN': Structured cause of an incident, across both incident sources. A superset of the worker's wire ``FailureKind``: every value the worker can report is storable here, plus the causes only the core can observe (a heartbeat that never pinged, a client that reported its own failure). The two enums are declared separately so the worker contract does not grow values the worker never emits — ``test_enums.py`` guards the subset relation, which is what keeps ``process_check_result`` able to store any incoming ``failure_kind``. The raw human-readable reason lives in ``Incident.cause_detail``.
- `period_days` integer, nullable: Only incidents that were active within the last N days. An incident still open is always included, whenever it started. Combined with status=open this makes period_days a no-op, since every open incident already satisfies that arm — use status=resolved or omit status to see the window take effect.
- `page` integer
- `size` integer

## Headers

- `X-Organization-Id` string, uuid, nullable

## Response `200`

Successful Response

- PaginatedResponseIncidentRead
  - `items` IncidentRead[], required
    - `id` string, uuid, required
    - `monitor_id` string, uuid, nullable
    - `heartbeat_id` string, uuid, nullable
    - `started_at` string, date-time, required
    - `resolved_at` string, date-time, nullable, required
    - `cause` 'TIMEOUT' | 'DNS_FAILURE' | 'CONNECTION_REFUSED' | 'TLS_INVALID' | 'HTTP_4XX' | 'HTTP_5XX' | 'HTTP_UNEXPECTED_STATUS' | 'KEYWORD_MISSING' | 'TOO_MANY_REDIRECTS' | 'TARGET_BLOCKED' | 'PORT_STATE_MISMATCH' | 'INVALID_TARGET' | 'HEARTBEAT_MISSED' | 'HEARTBEAT_FAILED' | 'UNKNOWN', required: Structured cause of an incident, across both incident sources. A superset of the worker's wire ``FailureKind``: every value the worker can report is storable here, plus the causes only the core can observe (a heartbeat that never pinged, a client that reported its own failure). The two enums are declared separately so the worker contract does not grow values the worker never emits — ``test_enums.py`` guards the subset relation, which is what keeps ``process_check_result`` able to store any incoming ``failure_kind``. The raw human-readable reason lives in ``Incident.cause_detail``.
    - `cause_detail` string, nullable, required
    - `last_notified_at` string, date-time, nullable, required
    - `acknowledged_at` string, date-time, nullable, required
    - `acknowledged_by` string, uuid, nullable, required
    - `renotify_count` integer, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `notification_logs` NotificationLogRead[]
      - `id` string, uuid, required
      - `channel_type` 'EMAIL' | 'TELEGRAM' | 'WEBHOOK' | 'SLACK' | 'DISCORD', required: Transport for a user notification channel.
      - `destination` string, required
      - `event` 'TRIGGERED' | 'RESOLVED' | 'SSL_EXPIRY', required: Lifecycle event that triggered an outgoing notification.
      - `sent_at` string, date-time, required
      - `status` 'PENDING' | 'SENT' | 'FAILED', required: Delivery outcome for an outgoing notification.
      - `error` string, nullable, required
  - `total` integer, required
  - `page` integer, required
  - `size` integer, required
  - `pages` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fettle/apis/fettle-sh.md) · [All operations](https://skmtc.dev/fettle/apis/fettle-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/fettle/apis/fettle-sh/revisions/f32c8a18606f?raw)