Skip to Content

Get an incident

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

HTTP
Authorization: Bearer $RESPAN_API_KEY

Path parameters

Parameter Type Required Description and constraints
incident_id string Required
Incident ID, from List incidents.
Example: "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"

Request body

The request body is optional.

application/json

Field Type Requirement Description and constraints
$ object Optional body
-

OpenAPI request schema

{
  "type": "object"
}
Example
JSON
{}

Responses

200

The incident.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/ErrorIncidentDetail
incident object Required in parent
The incident, with exact impact, error_count and request_count, and dominant_fingerprint set from the top error group.
incident (allOf 1) object Schema variant
A window where one environment’s error rate for one fault domain rose well above its usual level.
Reference: #/components/schemas/ErrorIncident
incident (allOf 1).id string Required in parent
Incident ID.
Example: "3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805"
incident (allOf 1).title string Required in parent
Main error class and environment, in words.
Example: "Provider rate limit in prod"
incident (allOf 1).environment string Required in parent
Example: "prod"
incident (allOf 1).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"
incident (allOf 1).started_at string Required in parent
Format: date-time
Example: "2026-09-30T14:02:00Z"
incident (allOf 1).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"
incident (allOf 1).duration_seconds integer Required in parent
From started_at to data_through_at.
Example: 2700
incident (allOf 1).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"
incident (allOf 1).state string Required in parent
Allowed: "ongoing", "past"
Example: "past"
incident (allOf 1).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"
incident (allOf 1).severity string Required in parent
Allowed: "low", "medium", "high", "critical"
Example: "high"
incident (allOf 1).trigger string Required in parent
spike for a sudden jump, drift for a sustained smaller rise.
Allowed: "spike", "drift"
Example: "spike"
incident (allOf 1).peak_error_rate number Required in parent
A fraction from 0 to 1.
Example: 0.42
incident (allOf 1).baseline_error_rate number Required in parent
A fraction from 0 to 1.
Example: 0.012
incident (allOf 1).error_count integer Required in parent
Example: 1840
incident (allOf 1).request_count integer Required in parent
Example: 9620
incident (allOf 1).hot_bucket_count integer Required in parent
Minutes that tripped the detector.
Example: 31
incident (allOf 1).error_class_breakdown object Required in parent
Failed requests per error class.
Example: {"provider_rate_limit":1702,"provider_overloaded":138}
incident (allOf 1).error_class_breakdown.<key> integer Map value
-
incident (allOf 1).dominant_error_class string Required in parent
Most common error class.
Example: "provider_rate_limit"
incident (allOf 1).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"
incident (allOf 1).impact object Required in parent
Reference: #/components/schemas/ErrorIncidentImpact
incident (allOf 1).impact.error_count integer Required in parent
Failed requests in the incident window.
Example: 1840
incident (allOf 1).impact.request_count integer Required in parent
All requests in the incident’s environment over the window.
Example: 9620
incident (allOf 1).impact.error_rate number Required in parent
error_count / request_count. A fraction from 0 to 1.
Example: 0.191
incident (allOf 1).impact.peak_error_rate number Required in parent
Highest one-minute error rate. A fraction from 0 to 1.
Example: 0.42
incident (allOf 1).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
incident (allOf 1).impact.rate_delta number Required in parent
error_rate minus baseline_error_rate.
Example: 0.179
incident (allOf 1).impact.rate_multiplier number or null Required in parent
error_rate / baseline_error_rate, or null when the baseline is 0.
Example: 15.9
incident (allOf 1).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
incident (allOf 1).impact.affected_customers integer Optional
Distinct customers with a failed request. Only in Get an incident.
Example: 37
incident (allOf 1).primary_error object Required in parent
-
incident (allOf 1).primary_error.error_class string Required in parent
Example: "provider_rate_limit"
incident (allOf 1).primary_error.fingerprint string or null Required in parent
Example: "9F3B2C1D4E5A6B7C"
incident (allOf 1).acknowledged_at string or null Required in parent
Format: date-time
Example: null
incident (allOf 1).is_acknowledged boolean Required in parent
Example: false
incident (allOf 1).notes string Required in parent
Team notes. Visible to everyone in the organization.
Example: ""
incident (allOf 1).created_at string Required in parent
Format: date-time
Example: "2026-09-30T14:05:12.448210Z"
incident (allOf 1).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"
affected object Required in parent
Reference: #/components/schemas/ErrorIncidentAffected
affected.providers object Required in parent
Reference: #/components/schemas/ErrorIncidentAffectedDimension
affected.providers.unique_count integer Required in parent
Distinct values hit.
Example: 2
affected.providers.total_occurrences integer Required in parent
Example: 1840
affected.providers.values array<object> Required in parent
Top 10 values by failures.
affected.providers.values[] object Array item
Reference: #/components/schemas/ErrorIncidentAffectedValue
affected.providers.values[].value string Required in parent
Example: "openai"
affected.providers.values[].occurrence_count integer Required in parent
Failed requests with this value.
Example: 1702
affected.providers.values[].percentage number Required in parent
Share of the dimension’s failures, 0 to 100.
Example: 92.5
affected.providers.values[].first_seen_at string Required in parent
First failure with this value. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:02:03.517203"
affected.providers.values[].last_seen_at string Required in parent
Latest failure with this value. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:46:58.006114"
affected.models object Required in parent
Reference: #/components/schemas/ErrorIncidentAffectedDimension
affected.models.unique_count integer Required in parent
Distinct values hit.
Example: 2
affected.models.total_occurrences integer Required in parent
Example: 1840
affected.models.values array<object> Required in parent
Top 10 values by failures.
affected.models.values[] object Array item
Reference: #/components/schemas/ErrorIncidentAffectedValue
affected.models.values[].value string Required in parent
Example: "openai"
affected.models.values[].occurrence_count integer Required in parent
Failed requests with this value.
Example: 1702
affected.models.values[].percentage number Required in parent
Share of the dimension’s failures, 0 to 100.
Example: 92.5
affected.models.values[].first_seen_at string Required in parent
First failure with this value. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:02:03.517203"
affected.models.values[].last_seen_at string Required in parent
Latest failure with this value. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:46:58.006114"
affected.endpoints object Required in parent
Reference: #/components/schemas/ErrorIncidentAffectedDimension
affected.endpoints.unique_count integer Required in parent
Distinct values hit.
Example: 2
affected.endpoints.total_occurrences integer Required in parent
Example: 1840
affected.endpoints.values array<object> Required in parent
Top 10 values by failures.
affected.endpoints.values[] object Array item
Reference: #/components/schemas/ErrorIncidentAffectedValue
affected.endpoints.values[].value string Required in parent
Example: "openai"
affected.endpoints.values[].occurrence_count integer Required in parent
Failed requests with this value.
Example: 1702
affected.endpoints.values[].percentage number Required in parent
Share of the dimension’s failures, 0 to 100.
Example: 92.5
affected.endpoints.values[].first_seen_at string Required in parent
First failure with this value. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:02:03.517203"
affected.endpoints.values[].last_seen_at string Required in parent
Latest failure with this value. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:46:58.006114"
affected.customers object Required in parent
Reference: #/components/schemas/ErrorIncidentAffectedDimension
affected.customers.unique_count integer Required in parent
Distinct values hit.
Example: 2
affected.customers.total_occurrences integer Required in parent
Example: 1840
affected.customers.values array<object> Required in parent
Top 10 values by failures.
affected.customers.values[] object Array item
Reference: #/components/schemas/ErrorIncidentAffectedValue
affected.customers.values[].value string Required in parent
Example: "openai"
affected.customers.values[].occurrence_count integer Required in parent
Failed requests with this value.
Example: 1702
affected.customers.values[].percentage number Required in parent
Share of the dimension’s failures, 0 to 100.
Example: 92.5
affected.customers.values[].first_seen_at string Required in parent
First failure with this value. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:02:03.517203"
affected.customers.values[].last_seen_at string Required in parent
Latest failure with this value. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:46:58.006114"
contributors object Required in parent
Reference: #/components/schemas/ErrorIncidentContributors
contributors.items array<object> Required in parent
Top 20 error groups by failures.
contributors.items[] object Array item
Reference: #/components/schemas/ErrorIncidentContributor
contributors.items[].fingerprint string Required in parent
Error group fingerprint.
Example: "9F3B2C1D4E5A6B7C"
contributors.items[].title string Required in parent
Example: "provider_rate_limit · openai chat/completions · 429"
contributors.items[].error_class string Required in parent
Example: "provider_rate_limit"
contributors.items[].provider string Required in parent
Example: "openai"
contributors.items[].model string Required in parent
Model of the group’s latest failure.
Example: "gpt-4o"
contributors.items[].endpoint string Required in parent
Example: "chat/completions"
contributors.items[].status integer Required in parent
Example: 429
contributors.items[].occurrence_count integer Required in parent
Example: 1702
contributors.items[].percentage number Required in parent
Share of the incident’s failures, 0 to 100.
Example: 92.5
contributors.items[].affected_customers integer Required in parent
Distinct customers with a failure in this group.
Example: 35
contributors.items[].first_seen_at string Required in parent
First failure in the incident. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:02:03.517203"
contributors.items[].last_seen_at string Required in parent
Latest failure in the incident. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:46:58.006114"
contributors.items[].error_group_url string or null Required in parent
Path of Get an error group for this fingerprint.
Example: "/api/pulses/errors/9f3b2c1d4e5a6b7c/"
contributors.items[].drilldown_filters object Required in parent
Time range and environment to pass to Get an error group to see the same failures.
contributors.items[].drilldown_filters.start_time string Required in parent
UTC, YYYY-MM-DD HH:MM:SS.
Example: "2026-09-30 14:02:00"
contributors.items[].drilldown_filters.end_time string Required in parent
UTC, YYYY-MM-DD HH:MM:SS.
Example: "2026-09-30 14:47:00"
contributors.items[].drilldown_filters.environment string Required in parent
Example: "prod"
contributors.total_groups integer Required in parent
Error groups in the incident.
Example: 2
contributors.total_occurrences integer Required in parent
Failed requests in the incident.
Example: 1840
contributors.other_occurrences integer Required in parent
Failures in groups past the top 20.
Example: 0
occurrence_preview array<object> Required in parent
The 20 most recent failed requests.
occurrence_preview[] object Array item
Reference: #/components/schemas/ErrorIncidentOccurrence
occurrence_preview[].unique_id string Required in parent
Span ID.
Example: "1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a"
occurrence_preview[].timestamp string Required in parent
When the request failed. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:46:58.006114"
occurrence_preview[].fingerprint string Required in parent
Example: "9F3B2C1D4E5A6B7C"
occurrence_preview[].error_class string Required in parent
Example: "provider_rate_limit"
occurrence_preview[].provider string Required in parent
Example: "openai"
occurrence_preview[].model string Required in parent
Example: "gpt-4o"
occurrence_preview[].endpoint string Required in parent
Example: "chat/completions"
occurrence_preview[].status integer Required in parent
Example: 429
occurrence_preview[].customer_identifier string Required in parent
Example: "acme-corp"
occurrence_preview[].error_group_url string or null Required in parent
Example: "/api/pulses/errors/9f3b2c1d4e5a6b7c/"
occurrence_preview[].log_url string or null Required in parent
Path of Get a span for this request.
Example: "/api/request-logs/1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a/"
data_status object Required in parent
-
data_status.is_partial boolean Required in parent
true when the breakdowns couldn’t be loaded. affected, contributors and occurrence_preview are then empty.
Example: false
data_status.data_through_at string Required in parent
Format: date-time
Example: "2026-09-30T14:47:00Z"
data_status.reason string or null Required in parent
analytics_unavailable when is_partial is true, else null.
Example: null
links object Required in parent
-
links.timeseries string Required in parent
Example: "/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/timeseries/"
links.acknowledgement string Required in parent
Example: "/api/pulses/incidents/3c9d7e1a-58b2-4f0e-a6d4-91c2b7e3f805/acknowledgement/"

OpenAPI response schema

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

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." }

404

No incident with this ID in your organization.

application/json

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

OpenAPI response schema

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
Example
JSON
{ "error": "incident not found" }

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": "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"
      }
    }
  }
}