> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# List incidents

POST https://api.respan.ai/api/pulses/incidents/
Content-Type: application/json

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.

Reference: https://respan.ai/docs/apis/errors/list-incidents

## Authentication

- `Authorization` header (bearer token, required) — 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.

## Request

### Query parameters

- `page` (integer, optional, default: 1) — Page number.
- `page_size` (integer, optional, default: 50) — Incidents per page. Values above 200 are capped at 200.

### Body (application/json)

This endpoint expects an ErrorIncidentListRequest.

- `start_time` (datetime, optional) — Start of the range, ISO 8601. Defaults to 7 days ago. Incidents that overlap the range are returned.
- `end_time` (datetime, optional) — End of the range, ISO 8601. Defaults to now.
- `state` (enum, optional) — Only incidents in this state.
  - Allowed values: `ongoing`, `past`
- `severity` (enum, optional) — Only incidents of this severity.
  - Allowed values: `low`, `medium`, `high`, `critical`
- `environment` (string, optional) — Only incidents in this environment.
- `fault_domain` (enum, optional) — Only incidents for this fault domain.
  - Allowed values: `user`, `respan`, `provider`, `none`

## Response

### 200

A page of incidents.

- `results` (list of ErrorIncident, required) — Incidents, newest first.
- `count` (integer, required) — Incidents on this page.
- `next` (string, required, nullable) — URL of the next page, or `null`.
- `previous` (string, required, nullable) — 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` (map from string to any, optional) — The filters that were applied.

## Errors

### 400 Bad Request Error

A filter value is invalid. The body maps the field to its errors.

- `map from string to list of string`

### 403 Forbidden Error

Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:read` (Read access does).

- `detail` (string, required)

### 429 Too Many Requests Error

Rate limited. This endpoint allows 60 requests per minute per organization.

- `detail` (string, required)

## Types

### ErrorIncident

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` (enum, 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).
  - Allowed values: `user`, `respan`, `provider`, `none`
- `started_at` (datetime, required)
- `ended_at` (datetime, required, nullable) — End of the last elevated minute, or `null` while ongoing.
- `duration_seconds` (integer, required) — From `started_at` to `data_through_at`.
- `data_through_at` (datetime, required) — How far the evidence goes: `ended_at` once past; for an ongoing incident, the latest minute that is fully ingested.
- `state` (enum, required)
  - Allowed values: `ongoing`, `past`
- `resolution_reason` (enum, required, nullable) — Why it ended: the rate recovered, requests stopped, or the scope went silent. `null` while ongoing.
  - Allowed values: `recovered`, `no_traffic`, `stale`
- `severity` (enum, required)
  - Allowed values: `low`, `medium`, `high`, `critical`
- `trigger` (enum, required) — `spike` for a sudden jump, `drift` for a sustained smaller rise.
  - Allowed values: `spike`, `drift`
- `peak_error_rate` (double, required) — A fraction from 0 to 1.
- `baseline_error_rate` (double, 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` (map from string to integer, required) — Failed requests per error class.
- `dominant_error_class` (string, required) — Most common error class.
- `dominant_fingerprint` (string, required, nullable) — Error group with the most failures. Usually `null` in List incidents; Get an incident fills it.
- `impact` (ErrorIncidentImpact, required)
- `primary_error` (ErrorIncidentPrimaryError, required)
- `acknowledged_at` (datetime, required, nullable)
- `is_acknowledged` (boolean, required)
- `notes` (string, required) — Team notes. Visible to everyone in the organization.
- `created_at` (datetime, required)
- `updated_at` (datetime, required) — When the detector last evaluated the incident. Acknowledging or editing notes doesn't change it.

### ErrorIncidentImpact

- `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` (double, required) — `error_count` / `request_count`. A fraction from 0 to 1.
- `peak_error_rate` (double, required) — Highest one-minute error rate. A fraction from 0 to 1.
- `baseline_error_rate` (double, required) — The scope's usual error rate when the incident was detected. A fraction from 0 to 1.
- `rate_delta` (double, required) — `error_rate` minus `baseline_error_rate`.
- `rate_multiplier` (double, required, nullable) — `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, optional) — Distinct customers with a failed request. Only in Get an incident.

### ErrorIncidentPrimaryError

- `error_class` (string, required)
- `fingerprint` (string, required, nullable)

## Examples

**Request**

```json
{
  "start_time": "2026-09-24T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "environment": "prod"
}
```

**Response**

```json
{
  "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"
  }
}
```

**SDK Code**

```python Incidents_listIncidents_example
import requests

url = "https://api.respan.ai/api/pulses/incidents/"

payload = {
    "start_time": "2026-09-24T00:00:00Z",
    "end_time": "2026-10-01T00:00:00Z",
    "environment": "prod"
}
headers = {
    "Authorization": "Bearer <respanApiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Incidents_listIncidents_example
const url = 'https://api.respan.ai/api/pulses/incidents/';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <respanApiKey>', 'Content-Type': 'application/json'},
  body: '{"start_time":"2026-09-24T00:00:00Z","end_time":"2026-10-01T00:00:00Z","environment":"prod"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Incidents_listIncidents_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.respan.ai/api/pulses/incidents/"

	payload := strings.NewReader("{\n  \"start_time\": \"2026-09-24T00:00:00Z\",\n  \"end_time\": \"2026-10-01T00:00:00Z\",\n  \"environment\": \"prod\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <respanApiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Incidents_listIncidents_example
require 'uri'
require 'net/http'

url = URI("https://api.respan.ai/api/pulses/incidents/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <respanApiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"start_time\": \"2026-09-24T00:00:00Z\",\n  \"end_time\": \"2026-10-01T00:00:00Z\",\n  \"environment\": \"prod\"\n}"

response = http.request(request)
puts response.read_body
```

```java Incidents_listIncidents_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.respan.ai/api/pulses/incidents/")
  .header("Authorization", "Bearer <respanApiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"start_time\": \"2026-09-24T00:00:00Z\",\n  \"end_time\": \"2026-10-01T00:00:00Z\",\n  \"environment\": \"prod\"\n}")
  .asString();
```

```php Incidents_listIncidents_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.respan.ai/api/pulses/incidents/', [
  'body' => '{
  "start_time": "2026-09-24T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "environment": "prod"
}',
  'headers' => [
    'Authorization' => 'Bearer <respanApiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Incidents_listIncidents_example
using RestSharp;

var client = new RestClient("https://api.respan.ai/api/pulses/incidents/");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <respanApiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"start_time\": \"2026-09-24T00:00:00Z\",\n  \"end_time\": \"2026-10-01T00:00:00Z\",\n  \"environment\": \"prod\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Incidents_listIncidents_example
import Foundation

let headers = [
  "Authorization": "Bearer <respanApiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "start_time": "2026-09-24T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "environment": "prod"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.respan.ai/api/pulses/incidents/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```