Get an incident
https://api.respan.ai/api/pulses/incidents/{incident_id}/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.
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_KEYPath parameters
incident_id string RequiredExample:
"3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"Request body
The request body is optional.
application/json
$ object Optional bodyOpenAPI request schema
{
"type": "object"
}Example
{}Responses
200
The incident.
application/json
$ object Body
#/components/schemas/ErrorIncidentDetailincident object Required in parent
impact, error_count and request_count, and dominant_fingerprint set from the top error group.incident (allOf 1) object Schema variant
Reference:
#/components/schemas/ErrorIncidentincident (allOf 1).id string Required in parentExample:
"3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"incident (allOf 1).title string Required in parentExample:
"Provider rate limit in prod"incident (allOf 1).environment string Required in parent"prod"incident (allOf 1).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"incident (allOf 1).started_at string Required in parentdate-timeExample:
"2026-09-30T14:02:00Z"incident (allOf 1).ended_at string or null Required in parentnull while ongoing.Format:
date-timeExample:
"2026-09-30T14:47:00Z"incident (allOf 1).duration_seconds integer Required in parentstarted_at to data_through_at.Example:
2700incident (allOf 1).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"incident (allOf 1).state string Required in parent"ongoing", "past"Example:
"past"incident (allOf 1).resolution_reason string or null Required in parentnull while ongoing.Allowed:
"recovered", "no_traffic", "stale"Example:
"recovered"incident (allOf 1).severity string Required in parent"low", "medium", "high", "critical"Example:
"high"incident (allOf 1).trigger string Required in parentspike for a sudden jump, drift for a sustained smaller rise.Allowed:
"spike", "drift"Example:
"spike"incident (allOf 1).peak_error_rate number Required in parentExample:
0.42incident (allOf 1).baseline_error_rate number Required in parentExample:
0.012incident (allOf 1).error_count integer Required in parent1840incident (allOf 1).request_count integer Required in parent9620incident (allOf 1).hot_bucket_count integer Required in parentExample:
31incident (allOf 1).error_class_breakdown object Required in parent
Example:
{"provider_rate_limit":1702,"provider_overloaded":138}incident (allOf 1).error_class_breakdown.<key> integer Map valueincident (allOf 1).dominant_error_class string Required in parentExample:
"provider_rate_limit"incident (allOf 1).dominant_fingerprint string or null Required in parentnull in List incidents; Get an incident fills it.Example:
"9F3B2C1D4E5A6B7C"incident (allOf 1).impact object Required in parent
#/components/schemas/ErrorIncidentImpactincident (allOf 1).impact.error_count integer Required in parentExample:
1840incident (allOf 1).impact.request_count integer Required in parentExample:
9620incident (allOf 1).impact.error_rate number Required in parenterror_count / request_count. A fraction from 0 to 1.Example:
0.191incident (allOf 1).impact.peak_error_rate number Required in parentExample:
0.42incident (allOf 1).impact.baseline_error_rate number Required in parentExample:
0.012incident (allOf 1).impact.rate_delta number Required in parenterror_rate minus baseline_error_rate.Example:
0.179incident (allOf 1).impact.rate_multiplier number or null Required in parenterror_rate / baseline_error_rate, or null when the baseline is 0.Example:
15.9incident (allOf 1).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:
falseincident (allOf 1).impact.affected_customers integer OptionalExample:
37incident (allOf 1).primary_error object Required in parent
incident (allOf 1).primary_error.error_class string Required in parent"provider_rate_limit"incident (allOf 1).primary_error.fingerprint string or null Required in parent"9F3B2C1D4E5A6B7C"incident (allOf 1).acknowledged_at string or null Required in parentdate-timeExample:
nullincident (allOf 1).is_acknowledged boolean Required in parentfalseincident (allOf 1).notes string Required in parentExample:
""incident (allOf 1).created_at string Required in parentdate-timeExample:
"2026-09-30T14:05:12.448210Z"incident (allOf 1).updated_at string Required in parentFormat:
date-timeExample:
"2026-09-30T14:52:03.118604Z"affected object Required in parent
#/components/schemas/ErrorIncidentAffectedaffected.providers object Required in parent
#/components/schemas/ErrorIncidentAffectedDimensionaffected.providers.unique_count integer Required in parentExample:
2affected.providers.total_occurrences integer Required in parent1840affected.providers.values array<object> Required in parent
affected.providers.values[] object Array item
#/components/schemas/ErrorIncidentAffectedValueaffected.providers.values[].value string Required in parent"openai"affected.providers.values[].occurrence_count integer Required in parentExample:
1702affected.providers.values[].percentage number Required in parentExample:
92.5affected.providers.values[].first_seen_at string Required in parentExample:
"2026-09-30T14:02:03.517203"affected.providers.values[].last_seen_at string Required in parentExample:
"2026-09-30T14:46:58.006114"affected.models object Required in parent
#/components/schemas/ErrorIncidentAffectedDimensionaffected.models.unique_count integer Required in parentExample:
2affected.models.total_occurrences integer Required in parent1840affected.models.values array<object> Required in parent
affected.models.values[] object Array item
#/components/schemas/ErrorIncidentAffectedValueaffected.models.values[].value string Required in parent"openai"affected.models.values[].occurrence_count integer Required in parentExample:
1702affected.models.values[].percentage number Required in parentExample:
92.5affected.models.values[].first_seen_at string Required in parentExample:
"2026-09-30T14:02:03.517203"affected.models.values[].last_seen_at string Required in parentExample:
"2026-09-30T14:46:58.006114"affected.endpoints object Required in parent
#/components/schemas/ErrorIncidentAffectedDimensionaffected.endpoints.unique_count integer Required in parentExample:
2affected.endpoints.total_occurrences integer Required in parent1840affected.endpoints.values array<object> Required in parent
affected.endpoints.values[] object Array item
#/components/schemas/ErrorIncidentAffectedValueaffected.endpoints.values[].value string Required in parent"openai"affected.endpoints.values[].occurrence_count integer Required in parentExample:
1702affected.endpoints.values[].percentage number Required in parentExample:
92.5affected.endpoints.values[].first_seen_at string Required in parentExample:
"2026-09-30T14:02:03.517203"affected.endpoints.values[].last_seen_at string Required in parentExample:
"2026-09-30T14:46:58.006114"affected.customers object Required in parent
#/components/schemas/ErrorIncidentAffectedDimensionaffected.customers.unique_count integer Required in parentExample:
2affected.customers.total_occurrences integer Required in parent1840affected.customers.values array<object> Required in parent
affected.customers.values[] object Array item
#/components/schemas/ErrorIncidentAffectedValueaffected.customers.values[].value string Required in parent"openai"affected.customers.values[].occurrence_count integer Required in parentExample:
1702affected.customers.values[].percentage number Required in parentExample:
92.5affected.customers.values[].first_seen_at string Required in parentExample:
"2026-09-30T14:02:03.517203"affected.customers.values[].last_seen_at string Required in parentExample:
"2026-09-30T14:46:58.006114"contributors object Required in parent
#/components/schemas/ErrorIncidentContributorscontributors.items array<object> Required in parent
contributors.items[] object Array item
#/components/schemas/ErrorIncidentContributorcontributors.items[].fingerprint string Required in parentExample:
"9F3B2C1D4E5A6B7C"contributors.items[].title string Required in parent"provider_rate_limit · openai chat/completions · 429"contributors.items[].error_class string Required in parent"provider_rate_limit"contributors.items[].provider string Required in parent"openai"contributors.items[].model string Required in parentExample:
"gpt-4o"contributors.items[].endpoint string Required in parent"chat/completions"contributors.items[].status integer Required in parent429contributors.items[].occurrence_count integer Required in parent1702contributors.items[].percentage number Required in parentExample:
92.5contributors.items[].affected_customers integer Required in parentExample:
35contributors.items[].first_seen_at string Required in parentExample:
"2026-09-30T14:02:03.517203"contributors.items[].last_seen_at string Required in parentExample:
"2026-09-30T14:46:58.006114"contributors.items[].error_group_url string or null Required in parentExample:
"/api/pulses/errors/9f3b2c1d4e5a6b7c/"contributors.items[].drilldown_filters object Required in parent
contributors.items[].drilldown_filters.start_time string Required in parentYYYY-MM-DD HH:MM:SS.Example:
"2026-09-30 14:02:00"contributors.items[].drilldown_filters.end_time string Required in parentYYYY-MM-DD HH:MM:SS.Example:
"2026-09-30 14:47:00"contributors.items[].drilldown_filters.environment string Required in parent"prod"contributors.total_groups integer Required in parentExample:
2contributors.total_occurrences integer Required in parentExample:
1840contributors.other_occurrences integer Required in parentExample:
0occurrence_preview array<object> Required in parent
occurrence_preview[] object Array item
#/components/schemas/ErrorIncidentOccurrenceoccurrence_preview[].unique_id string Required in parentExample:
"1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a"occurrence_preview[].timestamp string Required in parentExample:
"2026-09-30T14:46:58.006114"occurrence_preview[].fingerprint string Required in parent"9F3B2C1D4E5A6B7C"occurrence_preview[].error_class string Required in parent"provider_rate_limit"occurrence_preview[].provider string Required in parent"openai"occurrence_preview[].model string Required in parent"gpt-4o"occurrence_preview[].endpoint string Required in parent"chat/completions"occurrence_preview[].status integer Required in parent429occurrence_preview[].customer_identifier string Required in parent"acme-corp"occurrence_preview[].error_group_url string or null Required in parent"/api/pulses/errors/9f3b2c1d4e5a6b7c/"occurrence_preview[].log_url string or null Required in parentExample:
"/api/request-logs/1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a/"data_status object Required in parent
data_status.is_partial boolean Required in parenttrue when the breakdowns couldn’t be loaded. affected, contributors and occurrence_preview are then empty.Example:
falsedata_status.data_through_at string Required in parentdate-timeExample:
"2026-09-30T14:47:00Z"data_status.reason string or null Required in parentanalytics_unavailable when is_partial is true, else null.Example:
nulllinks object Required in parent
links.timeseries string Required in parent"/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/timeseries/"links.acknowledgement string Required in parent"/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/acknowledgement/"OpenAPI response schema
{
"$ref": "#/components/schemas/ErrorIncidentDetail"
}Example
{
"incident": {
"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": "9F3B2C1D4E5A6B7C",
"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,
"affected_customers": 37
},
"primary_error": {
"error_class": "provider_rate_limit",
"fingerprint": "9F3B2C1D4E5A6B7C"
},
"acknowledged_at": null,
"is_acknowledged": false,
"notes": "",
"created_at": "2026-09-30T14:05:12.448210Z",
"updated_at": "2026-09-30T14:52:03.118604Z"
},
"affected": {
"providers": {
"unique_count": 1,
"total_occurrences": 1840,
"values": [
{
"value": "openai",
"occurrence_count": 1840,
"percentage": 100,
"first_seen_at": "2026-09-30T14:02:03.517203",
"last_seen_at": "2026-09-30T14:46:58.006114"
}
]
},
"models": {
"unique_count": 0,
"total_occurrences": 0,
"values": []
},
"endpoints": {
"unique_count": 0,
"total_occurrences": 0,
"values": []
},
"customers": {
"unique_count": 37,
"total_occurrences": 1840,
"values": []
}
},
"contributors": {
"items": [
{
"fingerprint": "9F3B2C1D4E5A6B7C",
"title": "provider_rate_limit · openai chat/completions · 429",
"error_class": "provider_rate_limit",
"provider": "openai",
"model": "gpt-4o",
"endpoint": "chat/completions",
"status": 429,
"occurrence_count": 1702,
"percentage": 92.5,
"affected_customers": 35,
"first_seen_at": "2026-09-30T14:02:03.517203",
"last_seen_at": "2026-09-30T14:46:58.006114",
"error_group_url": "/api/pulses/errors/9f3b2c1d4e5a6b7c/",
"drilldown_filters": {
"start_time": "2026-09-30 14:02:00",
"end_time": "2026-09-30 14:47:00",
"environment": "prod"
}
}
],
"total_groups": 2,
"total_occurrences": 1840,
"other_occurrences": 138
},
"occurrence_preview": [],
"data_status": {
"is_partial": false,
"data_through_at": "2026-09-30T14:47:00Z",
"reason": null
},
"links": {
"timeseries": "/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/timeseries/",
"acknowledgement": "/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/acknowledgement/"
}
}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."
}404
No incident with this ID in your organization.
application/json
$ object Body
error string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
}Example
{
"error": "incident not found"
}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": "Get an incident",
"operationId": "retrieveIncident",
"tags": [
"Incidents"
],
"description": "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.",
"parameters": [
{
"name": "incident_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Incident ID, from List incidents.",
"example": "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {}
}
}
},
"responses": {
"200": {
"description": "The incident.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorIncidentDetail"
},
"example": {
"incident": {
"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": "9F3B2C1D4E5A6B7C",
"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,
"affected_customers": 37
},
"primary_error": {
"error_class": "provider_rate_limit",
"fingerprint": "9F3B2C1D4E5A6B7C"
},
"acknowledged_at": null,
"is_acknowledged": false,
"notes": "",
"created_at": "2026-09-30T14:05:12.448210Z",
"updated_at": "2026-09-30T14:52:03.118604Z"
},
"affected": {
"providers": {
"unique_count": 1,
"total_occurrences": 1840,
"values": [
{
"value": "openai",
"occurrence_count": 1840,
"percentage": 100,
"first_seen_at": "2026-09-30T14:02:03.517203",
"last_seen_at": "2026-09-30T14:46:58.006114"
}
]
},
"models": {
"unique_count": 0,
"total_occurrences": 0,
"values": []
},
"endpoints": {
"unique_count": 0,
"total_occurrences": 0,
"values": []
},
"customers": {
"unique_count": 37,
"total_occurrences": 1840,
"values": []
}
},
"contributors": {
"items": [
{
"fingerprint": "9F3B2C1D4E5A6B7C",
"title": "provider_rate_limit · openai chat/completions · 429",
"error_class": "provider_rate_limit",
"provider": "openai",
"model": "gpt-4o",
"endpoint": "chat/completions",
"status": 429,
"occurrence_count": 1702,
"percentage": 92.5,
"affected_customers": 35,
"first_seen_at": "2026-09-30T14:02:03.517203",
"last_seen_at": "2026-09-30T14:46:58.006114",
"error_group_url": "/api/pulses/errors/9f3b2c1d4e5a6b7c/",
"drilldown_filters": {
"start_time": "2026-09-30 14:02:00",
"end_time": "2026-09-30 14:47:00",
"environment": "prod"
}
}
],
"total_groups": 2,
"total_occurrences": 1840,
"other_occurrences": 138
},
"occurrence_preview": [],
"data_status": {
"is_partial": false,
"data_through_at": "2026-09-30T14:47:00Z",
"reason": null
},
"links": {
"timeseries": "/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/timeseries/",
"acknowledgement": "/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/acknowledgement/"
}
}
}
}
},
"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."
}
}
}
}
}
},
"404": {
"description": "No incident with this ID in your organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "incident not found"
}
}
}
},
"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"
}
}
},
"ErrorIncidentAffected": {
"type": "object",
"required": [
"providers",
"models",
"endpoints",
"customers"
],
"properties": {
"providers": {
"$ref": "#/components/schemas/ErrorIncidentAffectedDimension"
},
"models": {
"$ref": "#/components/schemas/ErrorIncidentAffectedDimension"
},
"endpoints": {
"$ref": "#/components/schemas/ErrorIncidentAffectedDimension"
},
"customers": {
"$ref": "#/components/schemas/ErrorIncidentAffectedDimension"
}
}
},
"ErrorIncidentAffectedDimension": {
"type": "object",
"required": [
"unique_count",
"total_occurrences",
"values"
],
"properties": {
"unique_count": {
"type": "integer",
"description": "Distinct values hit.",
"example": 2
},
"total_occurrences": {
"type": "integer",
"example": 1840
},
"values": {
"type": "array",
"description": "Top 10 values by failures.",
"items": {
"$ref": "#/components/schemas/ErrorIncidentAffectedValue"
}
}
}
},
"ErrorIncidentAffectedValue": {
"type": "object",
"required": [
"value",
"occurrence_count",
"percentage",
"first_seen_at",
"last_seen_at"
],
"properties": {
"value": {
"type": "string",
"example": "openai"
},
"occurrence_count": {
"type": "integer",
"description": "Failed requests with this value.",
"example": 1702
},
"percentage": {
"type": "number",
"description": "Share of the dimension's failures, 0 to 100.",
"example": 92.5
},
"first_seen_at": {
"type": "string",
"description": "First failure with this value. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T14:02:03.517203"
},
"last_seen_at": {
"type": "string",
"description": "Latest failure with this value. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T14:46:58.006114"
}
}
},
"ErrorIncidentContributor": {
"type": "object",
"required": [
"fingerprint",
"title",
"error_class",
"provider",
"model",
"endpoint",
"status",
"occurrence_count",
"percentage",
"affected_customers",
"first_seen_at",
"last_seen_at",
"error_group_url",
"drilldown_filters"
],
"properties": {
"fingerprint": {
"type": "string",
"description": "Error group fingerprint.",
"example": "9F3B2C1D4E5A6B7C"
},
"title": {
"type": "string",
"example": "provider_rate_limit · openai chat/completions · 429"
},
"error_class": {
"type": "string",
"example": "provider_rate_limit"
},
"provider": {
"type": "string",
"example": "openai"
},
"model": {
"type": "string",
"description": "Model of the group's latest failure.",
"example": "gpt-4o"
},
"endpoint": {
"type": "string",
"example": "chat/completions"
},
"status": {
"type": "integer",
"example": 429
},
"occurrence_count": {
"type": "integer",
"example": 1702
},
"percentage": {
"type": "number",
"description": "Share of the incident's failures, 0 to 100.",
"example": 92.5
},
"affected_customers": {
"type": "integer",
"description": "Distinct customers with a failure in this group.",
"example": 35
},
"first_seen_at": {
"type": "string",
"description": "First failure in the incident. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T14:02:03.517203"
},
"last_seen_at": {
"type": "string",
"description": "Latest failure in the incident. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T14:46:58.006114"
},
"error_group_url": {
"type": "string",
"nullable": true,
"description": "Path of Get an error group for this fingerprint.",
"example": "/api/pulses/errors/9f3b2c1d4e5a6b7c/"
},
"drilldown_filters": {
"type": "object",
"required": [
"start_time",
"end_time",
"environment"
],
"description": "Time range and environment to pass to Get an error group to see the same failures.",
"properties": {
"start_time": {
"type": "string",
"description": "UTC, `YYYY-MM-DD HH:MM:SS`.",
"example": "2026-09-30 14:02:00"
},
"end_time": {
"type": "string",
"description": "UTC, `YYYY-MM-DD HH:MM:SS`.",
"example": "2026-09-30 14:47:00"
},
"environment": {
"type": "string",
"example": "prod"
}
}
}
}
},
"ErrorIncidentContributors": {
"type": "object",
"required": [
"items",
"total_groups",
"total_occurrences",
"other_occurrences"
],
"properties": {
"items": {
"type": "array",
"description": "Top 20 error groups by failures.",
"items": {
"$ref": "#/components/schemas/ErrorIncidentContributor"
}
},
"total_groups": {
"type": "integer",
"description": "Error groups in the incident.",
"example": 2
},
"total_occurrences": {
"type": "integer",
"description": "Failed requests in the incident.",
"example": 1840
},
"other_occurrences": {
"type": "integer",
"description": "Failures in groups past the top 20.",
"example": 0
}
}
},
"ErrorIncidentDetail": {
"type": "object",
"required": [
"incident",
"affected",
"contributors",
"occurrence_preview",
"data_status",
"links"
],
"properties": {
"incident": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorIncident"
}
],
"description": "The incident, with exact `impact`, `error_count` and `request_count`, and `dominant_fingerprint` set from the top error group."
},
"affected": {
"$ref": "#/components/schemas/ErrorIncidentAffected"
},
"contributors": {
"$ref": "#/components/schemas/ErrorIncidentContributors"
},
"occurrence_preview": {
"type": "array",
"description": "The 20 most recent failed requests.",
"items": {
"$ref": "#/components/schemas/ErrorIncidentOccurrence"
}
},
"data_status": {
"type": "object",
"required": [
"is_partial",
"data_through_at",
"reason"
],
"properties": {
"is_partial": {
"type": "boolean",
"description": "`true` when the breakdowns couldn't be loaded. `affected`, `contributors` and `occurrence_preview` are then empty.",
"example": false
},
"data_through_at": {
"type": "string",
"format": "date-time",
"example": "2026-09-30T14:47:00Z"
},
"reason": {
"type": "string",
"nullable": true,
"description": "`analytics_unavailable` when `is_partial` is `true`, else `null`.",
"example": null
}
}
},
"links": {
"type": "object",
"required": [
"timeseries",
"acknowledgement"
],
"properties": {
"timeseries": {
"type": "string",
"example": "/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/timeseries/"
},
"acknowledgement": {
"type": "string",
"example": "/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/acknowledgement/"
}
}
}
}
},
"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
}
}
},
"ErrorIncidentOccurrence": {
"type": "object",
"required": [
"unique_id",
"timestamp",
"fingerprint",
"error_class",
"provider",
"model",
"endpoint",
"status",
"customer_identifier",
"error_group_url",
"log_url"
],
"properties": {
"unique_id": {
"type": "string",
"description": "Span ID.",
"example": "1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a"
},
"timestamp": {
"type": "string",
"description": "When the request failed. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T14:46:58.006114"
},
"fingerprint": {
"type": "string",
"example": "9F3B2C1D4E5A6B7C"
},
"error_class": {
"type": "string",
"example": "provider_rate_limit"
},
"provider": {
"type": "string",
"example": "openai"
},
"model": {
"type": "string",
"example": "gpt-4o"
},
"endpoint": {
"type": "string",
"example": "chat/completions"
},
"status": {
"type": "integer",
"example": 429
},
"customer_identifier": {
"type": "string",
"example": "acme-corp"
},
"error_group_url": {
"type": "string",
"nullable": true,
"example": "/api/pulses/errors/9f3b2c1d4e5a6b7c/"
},
"log_url": {
"type": "string",
"nullable": true,
"description": "Path of Get a span for this request.",
"example": "/api/request-logs/1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a/"
}
}
}
},
"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"
}
}
}
}