Skip to Content

List incidents

POSThttps://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.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Query parameters

Parameter Type Required Description and constraints
page integer Optional
Page number.
Default: 1
Minimum: 1
page_size integer Optional
Incidents per page. Values above 200 are capped at 200.
Default: 50
Minimum: 1
Maximum: 200

Request body

The request body is optional.

application/json

Field Type Requirement Description and constraints
$ object Optional body
Reference: #/components/schemas/ErrorIncidentListRequest
start_time string Optional
Start of the range, ISO 8601. Defaults to 7 days ago. Incidents that overlap the range are returned.
Format: date-time
Example: "2026-09-24T00:00:00Z"
end_time string Optional
End of the range, ISO 8601. Defaults to now.
Format: date-time
Example: "2026-10-01T00:00:00Z"
state string Optional
Only incidents in this state.
Allowed: "ongoing", "past"
Example: "ongoing"
severity string Optional
Only incidents of this severity.
Allowed: "low", "medium", "high", "critical"
Example: "high"
environment string Optional
Only incidents in this environment.
Minimum length: 1
Example: "prod"
fault_domain string Optional
Only incidents for this fault domain.
Allowed: "user", "respan", "provider", "none"
Example: "provider"

OpenAPI request schema

{
  "$ref": "#/components/schemas/ErrorIncidentListRequest"
}
Example
JSON
{ "start_time": "2026-09-24T00:00:00Z", "end_time": "2026-10-01T00:00:00Z", "environment": "prod" }

Responses

200

A page of incidents.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/ErrorIncidentList
results array<object> Required in parent
Incidents, newest first.
results[] object Array item
A window where one environment’s error rate for one fault domain rose well above its usual level.
Reference: #/components/schemas/ErrorIncident
results[].id string Required in parent
Incident ID.
Example: "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"
results[].title string Required in parent
Main error class and environment, in words.
Example: "Provider rate limit in prod"
results[].environment string Required in parent
Example: "prod"
results[].fault_domain string Required in parent
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).
Reference: #/components/schemas/ErrorFaultDomain
Allowed: "user", "respan", "provider", "none"
Example: "respan"
results[].started_at string Required in parent
Format: date-time
Example: "2026-09-30T14:02:00Z"
results[].ended_at string or null Required in parent
End of the last elevated minute, or null while ongoing.
Format: date-time
Example: "2026-09-30T14:47:00Z"
results[].duration_seconds integer Required in parent
From started_at to data_through_at.
Example: 2700
results[].data_through_at string Required in parent
How far the evidence goes: ended_at once past; for an ongoing incident, the latest minute that is fully ingested.
Format: date-time
Example: "2026-09-30T14:47:00Z"
results[].state string Required in parent
Allowed: "ongoing", "past"
Example: "past"
results[].resolution_reason string or null Required in parent
Why it ended: the rate recovered, requests stopped, or the scope went silent. null while ongoing.
Allowed: "recovered", "no_traffic", "stale"
Example: "recovered"
results[].severity string Required in parent
Allowed: "low", "medium", "high", "critical"
Example: "high"
results[].trigger string Required in parent
spike for a sudden jump, drift for a sustained smaller rise.
Allowed: "spike", "drift"
Example: "spike"
results[].peak_error_rate number Required in parent
A fraction from 0 to 1.
Example: 0.42
results[].baseline_error_rate number Required in parent
A fraction from 0 to 1.
Example: 0.012
results[].error_count integer Required in parent
Example: 1840
results[].request_count integer Required in parent
Example: 9620
results[].hot_bucket_count integer Required in parent
Minutes that tripped the detector.
Example: 31
results[].error_class_breakdown object Required in parent
Failed requests per error class.
Example: {"provider_rate_limit":1702,"provider_overloaded":138}
results[].error_class_breakdown.<key> integer Map value
-
results[].dominant_error_class string Required in parent
Most common error class.
Example: "provider_rate_limit"
results[].dominant_fingerprint string or null Required in parent
Error group with the most failures. Usually null in List incidents; Get an incident fills it.
Example: "9F3B2C1D4E5A6B7C"
results[].impact object Required in parent
Reference: #/components/schemas/ErrorIncidentImpact
results[].impact.error_count integer Required in parent
Failed requests in the incident window.
Example: 1840
results[].impact.request_count integer Required in parent
All requests in the incident’s environment over the window.
Example: 9620
results[].impact.error_rate number Required in parent
error_count / request_count. A fraction from 0 to 1.
Example: 0.191
results[].impact.peak_error_rate number Required in parent
Highest one-minute error rate. A fraction from 0 to 1.
Example: 0.42
results[].impact.baseline_error_rate number Required in parent
The scope’s usual error rate when the incident was detected. A fraction from 0 to 1.
Example: 0.012
results[].impact.rate_delta number Required in parent
error_rate minus baseline_error_rate.
Example: 0.179
results[].impact.rate_multiplier number or null Required in parent
error_rate / baseline_error_rate, or null when the baseline is 0.
Example: 15.9
results[].impact.is_estimated boolean Required in parent
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
results[].impact.affected_customers integer Optional
Distinct customers with a failed request. Only in Get an incident.
Example: 37
results[].primary_error object Required in parent
-
results[].primary_error.error_class string Required in parent
Example: "provider_rate_limit"
results[].primary_error.fingerprint string or null Required in parent
Example: "9F3B2C1D4E5A6B7C"
results[].acknowledged_at string or null Required in parent
Format: date-time
Example: null
results[].is_acknowledged boolean Required in parent
Example: false
results[].notes string Required in parent
Team notes. Visible to everyone in the organization.
Example: ""
results[].created_at string Required in parent
Format: date-time
Example: "2026-09-30T14:05:12.448210Z"
results[].updated_at string Required in parent
When the detector last evaluated the incident. Acknowledging or editing notes doesn’t change it.
Format: date-time
Example: "2026-09-30T14:52:03.118604Z"
count integer Required in parent
Incidents on this page.
Example: 1
next string or null Required in parent
URL of the next page, or null.
Format: uri
Example: null
previous string or null Required in parent
URL of the previous page, or null.
Format: uri
Example: null
total_count integer Required in parent
Incidents matching the filters across all pages.
Example: 1
ongoing_count integer Required in parent
How many of those are ongoing.
Example: 0
current_filters object Optional
The filters that were applied.
Additional properties are allowed

OpenAPI response schema

{
  "$ref": "#/components/schemas/ErrorIncidentList"
}
Example
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, "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

Field Type Requirement Description and constraints
$ object Body
-
$.<key> array<string> Map value
-
$.<key>[] string Array item
-

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}
Example
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Missing or invalid API key
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }
Key lacks the permission
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "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"
      }
    }
  }
}