List incidents | Respan Docs

curl -X POST https://api.respan.ai/api/pulses/incidents/ \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "start_time": "2026-09-24T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "environment": "prod"
}'

{
  "results": [
    {
      "id": "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805",
      "title": "Provider rate limit in prod",
      "environment": "prod",
      "fault_domain": "respan",
      "started_at": "2026-09-30T14:02:00Z",
      "ended_at": "2026-09-30T14:47:00Z",
      "duration_seconds": 2700,
      "data_through_at": "2026-09-30T14:47:00Z",
      "state": "past",
      "resolution_reason": "recovered",
      "severity": "high",
      "trigger": "spike",
      "peak_error_rate": 0.42,
      "baseline_error_rate": 0.012,
      "error_count": 1840,
      "request_count": 9620,
      "hot_bucket_count": 31,
      "error_class_breakdown": {
        "provider_rate_limit": 1702,
        "provider_overloaded": 138
      },
      "dominant_error_class": "provider_rate_limit",
      "dominant_fingerprint": null,
      "impact": {
        "error_count": 1840,
        "request_count": 9620,
        "error_rate": 0.191,
        "peak_error_rate": 0.42,
        "baseline_error_rate": 0.012,
        "rate_delta": 0.179,
        "rate_multiplier": 15.9,
        "is_estimated": false
      },
      "primary_error": {
        "error_class": "provider_rate_limit",
        "fingerprint": null
      },
      "acknowledged_at": null,
      "is_acknowledged": false,
      "notes": "",
      "created_at": "2026-09-30T14:05:12.448210Z",
      "updated_at": "2026-09-30T14:52:03.118604Z"
    }
  ],
  "count": 1,
  "next": null,
  "previous": null,
  "total_count": 1,
  "ongoing_count": 0,
  "current_filters": {
    "environment": "prod"
  }
}

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.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Query parameters

pageintegerOptional>=1Defaults to 1

Page number.

page_sizeintegerOptional1-200Defaults to 50

Incidents per page. Values above 200 are capped at 200.

Request

This endpoint expects an object.

start_timedatetimeOptional

Start of the range, ISO 8601. Defaults to 7 days ago. Incidents that overlap the range are returned.

end_timedatetimeOptional

End of the range, ISO 8601. Defaults to now.

stateenumOptional

Only incidents in this state.

Allowed values:

severityenumOptional

Only incidents of this severity.

Allowed values:

environmentstringOptional>=1 character

Only incidents in this environment.

fault_domainenumOptional

Only incidents for this fault domain.

Allowed values:

Response

A page of incidents.

resultslist of objects

Incidents, newest first.

countinteger

Incidents on this page.

nextstring or nullformat: "uri"

URL of the next page, or null.

previousstring or nullformat: "uri"

URL of the previous page, or null.

total_countinteger

Incidents matching the filters across all pages.

ongoing_countinteger

How many of those are ongoing.

current_filtersmap from strings to anyOptional

The filters that were applied.

Errors

400

Bad Request Error

403

Forbidden Error

429

Too Many Requests Error