Get an error group
https://api.respan.ai/api/pulses/errors/{fingerprint}/Returns one error group’s counts, first and last seen, reach and triage state in a time range, with its most recent failed spans.
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
fingerprint string RequiredExample:
"9F3B2C1D4E5A6B7C"Request body
The request body is optional.
application/json
$ object Optional body
#/components/schemas/ErrorGroupDetailRequeststart_time string OptionalFormat:
date-timeExample:
"2026-09-24T00:00:00Z"end_time string OptionalFormat:
date-timeExample:
"2026-10-01T00:00:00Z"environment string Optionalprod or test. Omit it to include every environment.Example:
"prod"limit integer Optionaloccurrences. Values above 500 are capped at 500.Default:
50Minimum:
1Maximum:
500Example:
20OpenAPI request schema
{
"$ref": "#/components/schemas/ErrorGroupDetailRequest"
}Example
{
"start_time": "2026-09-30T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"limit": 20
}Responses
200
The error group.
application/json
$ object and object Body
#/components/schemas/ErrorGroupDetail$ (allOf 1) object Schema variant
Reference:
#/components/schemas/ErrorGroup$ (allOf 1).fingerprint string Required in parentExample:
"9F3B2C1D4E5A6B7C"$ (allOf 1).title string Required in parentExample:
"provider_rate_limit · openai chat/completions · 429"$ (allOf 1).error_class string Required in parentReference:
#/components/schemas/ErrorClassAllowed:
"user_invalid_request", "user_auth_byok", "user_quota", "user_rate_limit", "user_content_policy", "user_context_window", "user_payload_too_large", "provider_down", "provider_overloaded", "provider_timeout", "provider_rate_limit", "respan_managed_auth", "respan_managed_billing", "respan_config", "respan_internal", "network_transient", "client_cancelled", "unknown"Example:
"provider_rate_limit"$ (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"$ (allOf 1).level string Required in parentops_page for errors Respan pages its on-call for, ops_log for the rest, none for cancellations.Allowed:
"none", "ops_log", "ops_page"Example:
"ops_page"$ (allOf 1).provider string Required in parentExample:
"openai"$ (allOf 1).endpoint string Required in parentchat/completions, responses or embeddings.Example:
"chat/completions"$ (allOf 1).status integer Required in parentExample:
429$ (allOf 1).count integer Required in parentExample:
318$ (allOf 1).first_seen string Required in parentExample:
"2026-09-30T02:14:51.004112"$ (allOf 1).last_seen string Required in parentExample:
"2026-09-30T23:58:12.771045"$ (allOf 1).affected_customers integer Required in parentcustomer_identifier values among the failures. Spans without one count as one value.Example:
41$ (allOf 1).affected_models integer Required in parentExample:
2$ (allOf 1).resolution string Required in parentunresolved.Reference:
#/components/schemas/ErrorResolutionStatusAllowed:
"unresolved", "resolved", "ignored"Example:
"unresolved"$ (allOf 2) object Schema variant
$ (allOf 2).occurrences array<object> Required in parent
$ (allOf 2).occurrences[] object Array item
#/components/schemas/ErrorGroupOccurrence$ (allOf 2).occurrences[].unique_id string Required in parentExample:
"1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a"$ (allOf 2).occurrences[].model string Required in parent"gpt-4o"$ (allOf 2).occurrences[].status string Required in parentfailed.Example:
"failed"$ (allOf 2).occurrences[].status_code integer Required in parentExample:
429$ (allOf 2).occurrences[].customer_identifier string Required in parentExample:
"acme-corp"$ (allOf 2).occurrences[].environment string Required in parent"prod"$ (allOf 2).occurrences[].timestamp string Required in parentExample:
"2026-09-30T23:58:12.771045"OpenAPI response schema
{
"$ref": "#/components/schemas/ErrorGroupDetail"
}Example
{
"fingerprint": "9F3B2C1D4E5A6B7C",
"title": "provider_rate_limit · openai chat/completions · 429",
"error_class": "provider_rate_limit",
"fault_domain": "respan",
"level": "ops_page",
"provider": "openai",
"endpoint": "chat/completions",
"status": 429,
"count": 318,
"first_seen": "2026-09-30T02:14:51.004112",
"last_seen": "2026-09-30T23:58:12.771045",
"affected_customers": 41,
"affected_models": 2,
"resolution": "unresolved",
"occurrences": [
{
"unique_id": "1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a",
"model": "gpt-4o",
"status": "failed",
"status_code": 429,
"customer_identifier": "acme-corp",
"environment": "prod",
"timestamp": "2026-09-30T23:58:12.771045"
}
]
}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
The group has no failures in the time range.
application/json
$ object Body
error string Required in parentfingerprint string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"error",
"fingerprint"
],
"properties": {
"error": {
"type": "string"
},
"fingerprint": {
"type": "string"
}
}
}Example
{
"error": "issue not found in window",
"fingerprint": "9F3B2C1D4E5A6B7C"
}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 error group",
"operationId": "retrieveErrorGroup",
"tags": [
"Error Groups"
],
"description": "Returns one error group's counts, first and last seen, reach and triage state in a time range, with its most recent failed spans.",
"parameters": [
{
"name": "fingerprint",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Error group fingerprint from List error groups: 16 uppercase hex characters, case-sensitive.",
"example": "9F3B2C1D4E5A6B7C"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorGroupDetailRequest"
},
"example": {
"start_time": "2026-09-30T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"limit": 20
}
}
}
},
"responses": {
"200": {
"description": "The error group.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorGroupDetail"
},
"example": {
"fingerprint": "9F3B2C1D4E5A6B7C",
"title": "provider_rate_limit · openai chat/completions · 429",
"error_class": "provider_rate_limit",
"fault_domain": "respan",
"level": "ops_page",
"provider": "openai",
"endpoint": "chat/completions",
"status": 429,
"count": 318,
"first_seen": "2026-09-30T02:14:51.004112",
"last_seen": "2026-09-30T23:58:12.771045",
"affected_customers": 41,
"affected_models": 2,
"resolution": "unresolved",
"occurrences": [
{
"unique_id": "1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a",
"model": "gpt-4o",
"status": "failed",
"status_code": 429,
"customer_identifier": "acme-corp",
"environment": "prod",
"timestamp": "2026-09-30T23:58:12.771045"
}
]
}
}
}
},
"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": "The group has no failures in the time range.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error",
"fingerprint"
],
"properties": {
"error": {
"type": "string"
},
"fingerprint": {
"type": "string"
}
}
},
"example": {
"error": "issue not found in window",
"fingerprint": "9F3B2C1D4E5A6B7C"
}
}
}
},
"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": {
"ErrorClass": {
"type": "string",
"enum": [
"user_invalid_request",
"user_auth_byok",
"user_quota",
"user_rate_limit",
"user_content_policy",
"user_context_window",
"user_payload_too_large",
"provider_down",
"provider_overloaded",
"provider_timeout",
"provider_rate_limit",
"respan_managed_auth",
"respan_managed_billing",
"respan_config",
"respan_internal",
"network_transient",
"client_cancelled",
"unknown"
],
"description": "Normalized cause of the failure, assigned when the span is stored.",
"example": "provider_rate_limit"
},
"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"
},
"ErrorGroup": {
"type": "object",
"description": "Failed spans that share one fingerprint.",
"required": [
"fingerprint",
"title",
"error_class",
"fault_domain",
"level",
"provider",
"endpoint",
"status",
"count",
"first_seen",
"last_seen",
"affected_customers",
"affected_models",
"resolution"
],
"properties": {
"fingerprint": {
"type": "string",
"description": "Error group ID: a hash of error class, provider, endpoint and status code. 16 uppercase hex characters.",
"example": "9F3B2C1D4E5A6B7C"
},
"title": {
"type": "string",
"description": "Readable name: error class, provider and endpoint, and status code.",
"example": "provider_rate_limit · openai chat/completions · 429"
},
"error_class": {
"$ref": "#/components/schemas/ErrorClass"
},
"fault_domain": {
"$ref": "#/components/schemas/ErrorFaultDomain"
},
"level": {
"type": "string",
"enum": [
"none",
"ops_log",
"ops_page"
],
"description": "Respan's ops alert level for the error class: `ops_page` for errors Respan pages its on-call for, `ops_log` for the rest, `none` for cancellations.",
"example": "ops_page"
},
"provider": {
"type": "string",
"description": "Provider ID.",
"example": "openai"
},
"endpoint": {
"type": "string",
"description": "Upstream operation, such as `chat/completions`, `responses` or `embeddings`.",
"example": "chat/completions"
},
"status": {
"type": "integer",
"description": "HTTP status code.",
"example": 429
},
"count": {
"type": "integer",
"description": "Failed spans in the group in the time range.",
"example": 318
},
"first_seen": {
"type": "string",
"description": "First failure in the range. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T02:14:51.004112"
},
"last_seen": {
"type": "string",
"description": "Latest failure in the range. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T23:58:12.771045"
},
"affected_customers": {
"type": "integer",
"description": "Distinct `customer_identifier` values among the failures. Spans without one count as one value.",
"example": 41
},
"affected_models": {
"type": "integer",
"description": "Distinct models among the failures.",
"example": 2
},
"resolution": {
"$ref": "#/components/schemas/ErrorResolutionStatus"
}
}
},
"ErrorGroupDetail": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorGroup"
},
{
"type": "object",
"required": [
"occurrences"
],
"properties": {
"occurrences": {
"type": "array",
"description": "Most recent failures in the group, newest first.",
"items": {
"$ref": "#/components/schemas/ErrorGroupOccurrence"
}
}
}
}
]
},
"ErrorGroupDetailRequest": {
"type": "object",
"properties": {
"start_time": {
"type": "string",
"format": "date-time",
"description": "Start of the range, ISO 8601. A time without an offset is read as UTC. Defaults to 7 days ago, which is also used if the value can't be parsed.",
"example": "2026-09-24T00:00:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"description": "End of the range, ISO 8601. A time without an offset is read as UTC. Defaults to now, which is also used if the value can't be parsed.",
"example": "2026-10-01T00:00:00Z"
},
"environment": {
"type": "string",
"description": "Only count spans from this environment, such as `prod` or `test`. Omit it to include every environment.",
"example": "prod"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"default": 50,
"description": "Most recent failures to return in `occurrences`. Values above 500 are capped at 500.",
"example": 20
}
}
},
"ErrorGroupOccurrence": {
"type": "object",
"required": [
"unique_id",
"model",
"status",
"status_code",
"customer_identifier",
"environment",
"timestamp"
],
"properties": {
"unique_id": {
"type": "string",
"description": "Span ID. Get a span returns its full request, response and error message.",
"example": "1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a"
},
"model": {
"type": "string",
"example": "gpt-4o"
},
"status": {
"type": "string",
"description": "Span status, such as `failed`.",
"example": "failed"
},
"status_code": {
"type": "integer",
"description": "HTTP status code.",
"example": 429
},
"customer_identifier": {
"type": "string",
"description": "Customer the span belongs to, if set.",
"example": "acme-corp"
},
"environment": {
"type": "string",
"example": "prod"
},
"timestamp": {
"type": "string",
"description": "When the span failed. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T23:58:12.771045"
}
}
},
"ErrorResolutionStatus": {
"type": "string",
"enum": [
"unresolved",
"resolved",
"ignored"
],
"description": "Triage state. Groups you haven't triaged are `unresolved`.",
"example": "unresolved"
}
},
"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"
}
}
}
}