--- title: "List incidents" method: POST path: "/api/pulses/incidents/" tags: ["Incidents"] --- # List incidents `POST /api/pulses/incidents/` ## Request - Base URL: `https://api.respan.ai` - URL: `https://api.respan.ai/api/pulses/incidents/` - Auth: HTTP bearer Lists windows where an environment's error rate rose well above its usual level, newest first, with how many are ongoing. Incidents count every request in the environment, not just the ones matching a filter. ## Query parameters - `page` integer - `page_size` integer ## Request body - ErrorIncidentListRequest - `start_time` string, date-time: Start of the range, ISO 8601. Defaults to 7 days ago. Incidents that overlap the range are returned. - `end_time` string, date-time: End of the range, ISO 8601. Defaults to now. - `state` 'ongoing' | 'past': Only incidents in this state. - `severity` 'low' | 'medium' | 'high' | 'critical': Only incidents of this severity. - `environment` string: Only incidents in this environment. - `fault_domain` 'user' | 'respan' | 'provider' | 'none': Only incidents for this fault domain. ## Response `200` A page of incidents. - ErrorIncidentList - `results` ErrorIncident[], required: Incidents, newest first. - `id` string, required: Incident ID. - `title` string, required: Main error class and environment, in words. - `environment` string, required - `fault_domain` 'user' | 'respan' | 'provider' | 'none', required: Whose fault the failure is, derived from `error_class`: `user` (your requests or your own provider keys), `provider` (the upstream provider), `respan` (Respan's gateway or managed capacity), or `none` (client cancellations). - `started_at` string, date-time, required - `ended_at` string, date-time, nullable, required: End of the last elevated minute, or `null` while ongoing. - `duration_seconds` integer, required: From `started_at` to `data_through_at`. - `data_through_at` string, date-time, required: How far the evidence goes: `ended_at` once past; for an ongoing incident, the latest minute that is fully ingested. - `state` 'ongoing' | 'past', required - `resolution_reason` 'recovered' | 'no_traffic' | 'stale', nullable, required: Why it ended: the rate recovered, requests stopped, or the scope went silent. `null` while ongoing. - `severity` 'low' | 'medium' | 'high' | 'critical', required - `trigger` 'spike' | 'drift', required: `spike` for a sudden jump, `drift` for a sustained smaller rise. - `peak_error_rate` number, required: A fraction from 0 to 1. - `baseline_error_rate` number, required: A fraction from 0 to 1. - `error_count` integer, required - `request_count` integer, required - `hot_bucket_count` integer, required: Minutes that tripped the detector. - `error_class_breakdown` object, required: Failed requests per error class. - `dominant_error_class` string, required: Most common error class. - `dominant_fingerprint` string, nullable, required: Error group with the most failures. Usually `null` in List incidents; Get an incident fills it. - `impact` ErrorIncidentImpact, required - `error_count` integer, required: Failed requests in the incident window. - `request_count` integer, required: All requests in the incident's environment over the window. - `error_rate` number, required: `error_count` / `request_count`. A fraction from 0 to 1. - `peak_error_rate` number, required: Highest one-minute error rate. A fraction from 0 to 1. - `baseline_error_rate` number, required: The scope's usual error rate when the incident was detected. A fraction from 0 to 1. - `rate_delta` number, required: `error_rate` minus `baseline_error_rate`. - `rate_multiplier` number, nullable, required: `error_rate` / `baseline_error_rate`, or `null` when the baseline is 0. - `is_estimated` boolean, required: `true` when the counts are the detector's estimate (incidents longer than 4 hours in List incidents). Get an incident returns exact counts. - `affected_customers` integer: Distinct customers with a failed request. Only in Get an incident. - `primary_error` object, required - `error_class` string, required - `fingerprint` string, nullable, required - `acknowledged_at` string, date-time, nullable, required - `is_acknowledged` boolean, required - `notes` string, required: Team notes. Visible to everyone in the organization. - `created_at` string, date-time, required - `updated_at` string, date-time, required: When the detector last evaluated the incident. Acknowledging or editing notes doesn't change it. - `count` integer, required: Incidents on this page. - `next` string, uri, nullable, required: URL of the next page, or `null`. - `previous` string, uri, nullable, required: URL of the previous page, or `null`. - `total_count` integer, required: Incidents matching the filters across all pages. - `ongoing_count` integer, required: How many of those are ongoing. - `current_filters` object: The filters that were applied. ## Other responses - `400`: A filter value is invalid. The body maps the field to its errors. - `403`: Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:read` (Read access does). - `429`: Rate limited. This endpoint allows 60 requests per minute per organization. ## Changes - **2026-10-21** `c30bcb383ee8`: 16 breaking, 3 warning, 4 info - the response property `next` became nullable for the status `200` - the response property `previous` became nullable for the status `200` - the response property `results/items/acknowledged_at` became nullable for the status `200` - the response property `results/items/dominant_fingerprint` became nullable for the status `200` - …19 more - **2026-10-02** `b830b79cfd52`: 1 info - endpoint added [Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/pulses/incidents/post.md) --- [API](https://skmtc.dev/respan/apis/respan-api.md) - [All operations](https://skmtc.dev/respan/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/respan/apis/respan-api/revisions/900841387635?raw)