--- title: "Get an incident" method: POST path: "/api/pulses/incidents/{incident_id}/" tags: ["Incidents"] --- # Get an incident `POST /api/pulses/incidents/{incident_id}/` ## Request - Base URL: `https://api.respan.ai` - URL: `https://api.respan.ai/api/pulses/incidents/{incident_id}/` - Auth: HTTP bearer Returns one incident with exact counts, the error groups behind it, the providers, models, endpoints and customers it hit, and its latest failed requests. Send an empty body. ## Path parameters - `incident_id` string, required ## Request body - object ## Response `200` The incident. - ErrorIncidentDetail - `incident` ErrorIncident, required: A window where one environment's error rate for one fault domain rose well above its usual level. - `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. - `affected` ErrorIncidentAffected, required - `providers` ErrorIncidentAffectedDimension, required - `unique_count` integer, required: Distinct values hit. - `total_occurrences` integer, required - `values` ErrorIncidentAffectedValue[], required: Top 10 values by failures. - `value` string, required - `occurrence_count` integer, required: Failed requests with this value. - `percentage` number, required: Share of the dimension's failures, 0 to 100. - `first_seen_at` string, required: First failure with this value. UTC, ISO 8601 without a timezone suffix. - `last_seen_at` string, required: Latest failure with this value. UTC, ISO 8601 without a timezone suffix. - `models` ErrorIncidentAffectedDimension, required - `unique_count` integer, required: Distinct values hit. - `total_occurrences` integer, required - `values` ErrorIncidentAffectedValue[], required: Top 10 values by failures. - `value` string, required - `occurrence_count` integer, required: Failed requests with this value. - `percentage` number, required: Share of the dimension's failures, 0 to 100. - `first_seen_at` string, required: First failure with this value. UTC, ISO 8601 without a timezone suffix. - `last_seen_at` string, required: Latest failure with this value. UTC, ISO 8601 without a timezone suffix. - `endpoints` ErrorIncidentAffectedDimension, required - `unique_count` integer, required: Distinct values hit. - `total_occurrences` integer, required - `values` ErrorIncidentAffectedValue[], required: Top 10 values by failures. - `value` string, required - `occurrence_count` integer, required: Failed requests with this value. - `percentage` number, required: Share of the dimension's failures, 0 to 100. - `first_seen_at` string, required: First failure with this value. UTC, ISO 8601 without a timezone suffix. - `last_seen_at` string, required: Latest failure with this value. UTC, ISO 8601 without a timezone suffix. - `customers` ErrorIncidentAffectedDimension, required - `unique_count` integer, required: Distinct values hit. - `total_occurrences` integer, required - `values` ErrorIncidentAffectedValue[], required: Top 10 values by failures. - `value` string, required - `occurrence_count` integer, required: Failed requests with this value. - `percentage` number, required: Share of the dimension's failures, 0 to 100. - `first_seen_at` string, required: First failure with this value. UTC, ISO 8601 without a timezone suffix. - `last_seen_at` string, required: Latest failure with this value. UTC, ISO 8601 without a timezone suffix. - `contributors` ErrorIncidentContributors, required - `items` ErrorIncidentContributor[], required: Top 20 error groups by failures. - `fingerprint` string, required: Error group fingerprint. - `title` string, required - `error_class` string, required - `provider` string, required - `model` string, required: Model of the group's latest failure. - `endpoint` string, required - `status` integer, required - `occurrence_count` integer, required - `percentage` number, required: Share of the incident's failures, 0 to 100. - `affected_customers` integer, required: Distinct customers with a failure in this group. - `first_seen_at` string, required: First failure in the incident. UTC, ISO 8601 without a timezone suffix. - `last_seen_at` string, required: Latest failure in the incident. UTC, ISO 8601 without a timezone suffix. - `error_group_url` string, nullable, required: Path of Get an error group for this fingerprint. - `drilldown_filters` object, required: Time range and environment to pass to Get an error group to see the same failures. - `start_time` string, required: UTC, `YYYY-MM-DD HH:MM:SS`. - `end_time` string, required: UTC, `YYYY-MM-DD HH:MM:SS`. - `environment` string, required - `total_groups` integer, required: Error groups in the incident. - `total_occurrences` integer, required: Failed requests in the incident. - `other_occurrences` integer, required: Failures in groups past the top 20. - `occurrence_preview` ErrorIncidentOccurrence[], required: The 20 most recent failed requests. - `unique_id` string, required: Span ID. - `timestamp` string, required: When the request failed. UTC, ISO 8601 without a timezone suffix. - `fingerprint` string, required - `error_class` string, required - `provider` string, required - `model` string, required - `endpoint` string, required - `status` integer, required - `customer_identifier` string, required - `error_group_url` string, nullable, required - `log_url` string, nullable, required: Path of Get a span for this request. - `data_status` object, required - `is_partial` boolean, required: `true` when the breakdowns couldn't be loaded. `affected`, `contributors` and `occurrence_preview` are then empty. - `data_through_at` string, date-time, required - `reason` string, nullable, required: `analytics_unavailable` when `is_partial` is `true`, else `null`. - `links` object, required - `timeseries` string, required - `acknowledgement` string, required ## Other responses - `403`: Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:read` (Read access does). - `404`: No incident with this ID in your organization. - `429`: Rate limited. This endpoint allows 60 requests per minute per organization. ## Changes - **2026-10-21** `c30bcb383ee8`: 37 breaking, 4 info - the response property `contributors/items/items/error_group_url` became nullable for the status `200` - the response property `data_status/reason` became nullable for the status `200` - the response property `occurrence_preview/items/error_group_url` became nullable for the status `200` - the response property `occurrence_preview/items/log_url` became nullable for the status `200` - …37 more - **2026-10-02** `b830b79cfd52`: 1 info - endpoint added [Operation history](https://skmtc.dev/keywordsai/apis/respan-api/changes/api/pulses/incidents/:incident_id/post.md) --- [API](https://skmtc.dev/keywordsai/apis/respan-api.md) - [All operations](https://skmtc.dev/keywordsai/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keywordsai/apis/respan-api/revisions/900841387635?raw)