List incidents
https://api.respan.ai/api/pulses/incidents/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.
Servers
https://api.respan.ai: Respan API Server
Authentication
RespanApiKey
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.
HTTP scheme: bearer; format: Respan API key.
Authorization: Bearer $RESPAN_API_KEYQuery parameters
page integer OptionalDefault:
1Minimum:
1page_size integer OptionalDefault:
50Minimum:
1Maximum:
200Request body
The request body is optional.
application/json
$ object Optional body
#/components/schemas/ErrorIncidentListRequeststart_time string OptionalFormat:
date-timeExample:
"2026-09-24T00:00:00Z"end_time string OptionalFormat:
date-timeExample:
"2026-10-01T00:00:00Z"state string OptionalAllowed:
"ongoing", "past"Example:
"ongoing"severity string OptionalAllowed:
"low", "medium", "high", "critical"Example:
"high"environment string OptionalMinimum length:
1Example:
"prod"fault_domain string OptionalAllowed:
"user", "respan", "provider", "none"Example:
"provider"OpenAPI request schema
{
"$ref": "#/components/schemas/ErrorIncidentListRequest"
}Example
{
"start_time": "2026-09-24T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"environment": "prod"
}Responses
200
A page of incidents.
application/json
$ object Body
#/components/schemas/ErrorIncidentListresults array<object> Required in parent
results[] object Array item
Reference:
#/components/schemas/ErrorIncidentresults[].id string Required in parentExample:
"3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"results[].title string Required in parentExample:
"Provider rate limit in prod"results[].environment string Required in parent"prod"results[].fault_domain string Required in parenterror_class: user (your requests or your own provider keys), provider (the upstream provider), respan (Respan’s gateway or managed capacity), or none (client cancellations).Reference:
#/components/schemas/ErrorFaultDomainAllowed:
"user", "respan", "provider", "none"Example:
"respan"results[].started_at string Required in parentdate-timeExample:
"2026-09-30T14:02:00Z"results[].ended_at string or null Required in parentnull while ongoing.Format:
date-timeExample:
"2026-09-30T14:47:00Z"results[].duration_seconds integer Required in parentstarted_at to data_through_at.Example:
2700results[].data_through_at string Required in parentended_at once past; for an ongoing incident, the latest minute that is fully ingested.Format:
date-timeExample:
"2026-09-30T14:47:00Z"results[].state string Required in parent"ongoing", "past"Example:
"past"results[].resolution_reason string or null Required in parentnull while ongoing.Allowed:
"recovered", "no_traffic", "stale"Example:
"recovered"results[].severity string Required in parent"low", "medium", "high", "critical"Example:
"high"results[].trigger string Required in parentspike for a sudden jump, drift for a sustained smaller rise.Allowed:
"spike", "drift"Example:
"spike"results[].peak_error_rate number Required in parentExample:
0.42results[].baseline_error_rate number Required in parentExample:
0.012results[].error_count integer Required in parent1840results[].request_count integer Required in parent9620results[].hot_bucket_count integer Required in parentExample:
31results[].error_class_breakdown object Required in parent
Example:
{"provider_rate_limit":1702,"provider_overloaded":138}results[].error_class_breakdown.<key> integer Map valueresults[].dominant_error_class string Required in parentExample:
"provider_rate_limit"results[].dominant_fingerprint string or null Required in parentnull in List incidents; Get an incident fills it.Example:
"9F3B2C1D4E5A6B7C"results[].impact object Required in parent
#/components/schemas/ErrorIncidentImpactresults[].impact.error_count integer Required in parentExample:
1840results[].impact.request_count integer Required in parentExample:
9620results[].impact.error_rate number Required in parenterror_count / request_count. A fraction from 0 to 1.Example:
0.191results[].impact.peak_error_rate number Required in parentExample:
0.42results[].impact.baseline_error_rate number Required in parentExample:
0.012results[].impact.rate_delta number Required in parenterror_rate minus baseline_error_rate.Example:
0.179results[].impact.rate_multiplier number or null Required in parenterror_rate / baseline_error_rate, or null when the baseline is 0.Example:
15.9results[].impact.is_estimated boolean Required in parenttrue when the counts are the detector’s estimate (incidents longer than 4 hours in List incidents). Get an incident returns exact counts.Example:
falseresults[].impact.affected_customers integer OptionalExample:
37results[].primary_error object Required in parent
results[].primary_error.error_class string Required in parent"provider_rate_limit"results[].primary_error.fingerprint string or null Required in parent"9F3B2C1D4E5A6B7C"results[].acknowledged_at string or null Required in parentdate-timeExample:
nullresults[].is_acknowledged boolean Required in parentfalseresults[].notes string Required in parentExample:
""results[].created_at string Required in parentdate-timeExample:
"2026-09-30T14:05:12.448210Z"results[].updated_at string Required in parentFormat:
date-timeExample:
"2026-09-30T14:52:03.118604Z"count integer Required in parentExample:
1next string or null Required in parentnull.Format:
uriExample:
nullprevious string or null Required in parentnull.Format:
uriExample:
nulltotal_count integer Required in parentExample:
1ongoing_count integer Required in parentExample:
0current_filters object OptionalAdditional properties are allowed
OpenAPI response schema
{
"$ref": "#/components/schemas/ErrorIncidentList"
}Example
{
"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,
"previous": null,
"next": null,
"total_count": 1,
"ongoing_count": 0,
"current_filters": {
"environment": "prod"
}
}400
A filter value is invalid. The body maps the field to its errors.
application/json
$ object Body
$.<key> array<string> Map value
$.<key>[] string Array itemOpenAPI response schema
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}Example
{
"state": [
"\"open\" is not a valid choice."
]
}403
Forbidden: the API key is missing, invalid or expired; the key doesn’t grant logs:read (Read access does).
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Missing or invalid API key
{
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}Key lacks the permission
{
"detail": "This API key does not have the 'logs:read' permission."
}429
Rate limited. This endpoint allows 60 requests per minute per organization.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Request was throttled."
}OpenAPI source
The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.
OpenAPI operation
{
"summary": "List incidents",
"operationId": "listIncidents",
"tags": [
"Incidents"
],
"description": "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.",
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number."
},
{
"name": "page_size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
},
"description": "Incidents per page. Values above 200 are capped at 200."
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorIncidentListRequest"
},
"example": {
"start_time": "2026-09-24T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"environment": "prod"
}
}
}
},
"responses": {
"200": {
"description": "A page of incidents.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorIncidentList"
},
"example": {
"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,
"previous": null,
"next": null,
"total_count": 1,
"ongoing_count": 0,
"current_filters": {
"environment": "prod"
}
}
}
}
},
"400": {
"description": "A filter value is invalid. The body maps the field to its errors.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"example": {
"state": [
"\"open\" is not a valid choice."
]
}
}
}
},
"403": {
"description": "Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:read` (Read access does).",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"examples": {
"invalidKey": {
"summary": "Missing or invalid API key",
"value": {
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
},
"missingPermission": {
"summary": "Key lacks the permission",
"value": {
"detail": "This API key does not have the 'logs:read' permission."
}
}
}
}
}
},
"429": {
"description": "Rate limited. This endpoint allows 60 requests per minute per organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Request was throttled."
}
}
}
}
},
"security": [
{
"RespanApiKey": []
}
]
}OpenAPI path metadata
{}Referenced OpenAPI components
{
"schemas": {
"ErrorFaultDomain": {
"type": "string",
"enum": [
"user",
"respan",
"provider",
"none"
],
"description": "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).",
"example": "respan"
},
"ErrorIncident": {
"type": "object",
"description": "A window where one environment's error rate for one fault domain rose well above its usual level.",
"required": [
"id",
"title",
"environment",
"fault_domain",
"started_at",
"ended_at",
"duration_seconds",
"data_through_at",
"state",
"resolution_reason",
"severity",
"trigger",
"peak_error_rate",
"baseline_error_rate",
"error_count",
"request_count",
"hot_bucket_count",
"error_class_breakdown",
"dominant_error_class",
"dominant_fingerprint",
"impact",
"primary_error",
"acknowledged_at",
"is_acknowledged",
"notes",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"description": "Incident ID.",
"example": "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"
},
"title": {
"type": "string",
"description": "Main error class and environment, in words.",
"example": "Provider rate limit in prod"
},
"environment": {
"type": "string",
"example": "prod"
},
"fault_domain": {
"$ref": "#/components/schemas/ErrorFaultDomain"
},
"started_at": {
"type": "string",
"format": "date-time",
"example": "2026-09-30T14:02:00Z"
},
"ended_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "End of the last elevated minute, or `null` while ongoing.",
"example": "2026-09-30T14:47:00Z"
},
"duration_seconds": {
"type": "integer",
"description": "From `started_at` to `data_through_at`.",
"example": 2700
},
"data_through_at": {
"type": "string",
"format": "date-time",
"description": "How far the evidence goes: `ended_at` once past; for an ongoing incident, the latest minute that is fully ingested.",
"example": "2026-09-30T14:47:00Z"
},
"state": {
"type": "string",
"enum": [
"ongoing",
"past"
],
"example": "past"
},
"resolution_reason": {
"type": "string",
"enum": [
"recovered",
"no_traffic",
"stale"
],
"nullable": true,
"description": "Why it ended: the rate recovered, requests stopped, or the scope went silent. `null` while ongoing.",
"example": "recovered"
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
],
"example": "high"
},
"trigger": {
"type": "string",
"enum": [
"spike",
"drift"
],
"description": "`spike` for a sudden jump, `drift` for a sustained smaller rise.",
"example": "spike"
},
"peak_error_rate": {
"type": "number",
"description": "A fraction from 0 to 1.",
"example": 0.42
},
"baseline_error_rate": {
"type": "number",
"description": "A fraction from 0 to 1.",
"example": 0.012
},
"error_count": {
"type": "integer",
"example": 1840
},
"request_count": {
"type": "integer",
"example": 9620
},
"hot_bucket_count": {
"type": "integer",
"description": "Minutes that tripped the detector.",
"example": 31
},
"error_class_breakdown": {
"type": "object",
"additionalProperties": {
"type": "integer"
},
"description": "Failed requests per error class.",
"example": {
"provider_rate_limit": 1702,
"provider_overloaded": 138
}
},
"dominant_error_class": {
"type": "string",
"description": "Most common error class.",
"example": "provider_rate_limit"
},
"dominant_fingerprint": {
"type": "string",
"nullable": true,
"description": "Error group with the most failures. Usually `null` in List incidents; Get an incident fills it.",
"example": "9F3B2C1D4E5A6B7C"
},
"impact": {
"$ref": "#/components/schemas/ErrorIncidentImpact"
},
"primary_error": {
"type": "object",
"required": [
"error_class",
"fingerprint"
],
"properties": {
"error_class": {
"type": "string",
"example": "provider_rate_limit"
},
"fingerprint": {
"type": "string",
"nullable": true,
"example": "9F3B2C1D4E5A6B7C"
}
}
},
"acknowledged_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": null
},
"is_acknowledged": {
"type": "boolean",
"example": false
},
"notes": {
"type": "string",
"description": "Team notes. Visible to everyone in the organization.",
"example": ""
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2026-09-30T14:05:12.448210Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the detector last evaluated the incident. Acknowledging or editing notes doesn't change it.",
"example": "2026-09-30T14:52:03.118604Z"
}
}
},
"ErrorIncidentImpact": {
"type": "object",
"required": [
"error_count",
"request_count",
"error_rate",
"peak_error_rate",
"baseline_error_rate",
"rate_delta",
"rate_multiplier",
"is_estimated"
],
"properties": {
"error_count": {
"type": "integer",
"description": "Failed requests in the incident window.",
"example": 1840
},
"request_count": {
"type": "integer",
"description": "All requests in the incident's environment over the window.",
"example": 9620
},
"error_rate": {
"type": "number",
"description": "`error_count` / `request_count`. A fraction from 0 to 1.",
"example": 0.191
},
"peak_error_rate": {
"type": "number",
"description": "Highest one-minute error rate. A fraction from 0 to 1.",
"example": 0.42
},
"baseline_error_rate": {
"type": "number",
"description": "The scope's usual error rate when the incident was detected. A fraction from 0 to 1.",
"example": 0.012
},
"rate_delta": {
"type": "number",
"description": "`error_rate` minus `baseline_error_rate`.",
"example": 0.179
},
"rate_multiplier": {
"type": "number",
"nullable": true,
"description": "`error_rate` / `baseline_error_rate`, or `null` when the baseline is 0.",
"example": 15.9
},
"is_estimated": {
"type": "boolean",
"description": "`true` when the counts are the detector's estimate (incidents longer than 4 hours in List incidents). Get an incident returns exact counts.",
"example": false
},
"affected_customers": {
"type": "integer",
"description": "Distinct customers with a failed request. Only in Get an incident.",
"example": 37
}
}
},
"ErrorIncidentList": {
"type": "object",
"required": [
"results",
"count",
"next",
"previous",
"total_count",
"ongoing_count"
],
"properties": {
"results": {
"type": "array",
"description": "Incidents, newest first.",
"items": {
"$ref": "#/components/schemas/ErrorIncident"
}
},
"count": {
"type": "integer",
"description": "Incidents on this page.",
"example": 1
},
"next": {
"type": "string",
"nullable": true,
"format": "uri",
"description": "URL of the next page, or `null`.",
"example": null
},
"previous": {
"type": "string",
"nullable": true,
"format": "uri",
"description": "URL of the previous page, or `null`.",
"example": null
},
"total_count": {
"type": "integer",
"description": "Incidents matching the filters across all pages.",
"example": 1
},
"ongoing_count": {
"type": "integer",
"description": "How many of those are ongoing.",
"example": 0
},
"current_filters": {
"type": "object",
"additionalProperties": true,
"description": "The filters that were applied."
}
}
},
"ErrorIncidentListRequest": {
"type": "object",
"properties": {
"start_time": {
"type": "string",
"format": "date-time",
"description": "Start of the range, ISO 8601. Defaults to 7 days ago. Incidents that overlap the range are returned.",
"example": "2026-09-24T00:00:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"description": "End of the range, ISO 8601. Defaults to now.",
"example": "2026-10-01T00:00:00Z"
},
"state": {
"type": "string",
"enum": [
"ongoing",
"past"
],
"description": "Only incidents in this state.",
"example": "ongoing"
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
],
"description": "Only incidents of this severity.",
"example": "high"
},
"environment": {
"type": "string",
"minLength": 1,
"description": "Only incidents in this environment.",
"example": "prod"
},
"fault_domain": {
"type": "string",
"enum": [
"user",
"respan",
"provider",
"none"
],
"description": "Only incidents for this fault domain.",
"example": "provider"
}
}
}
},
"securitySchemes": {
"RespanApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Respan API key",
"description": "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.",
"x-fern-bearer": {
"name": "respanApiKey",
"env": "RESPAN_API_KEY"
}
}
}
}