Skip to Content

Get an error group

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

HTTP
Authorization: Bearer $RESPAN_API_KEY

Path parameters

Parameter Type Required Description and constraints
fingerprint string Required
Error group fingerprint from List error groups: 16 uppercase hex characters, case-sensitive.
Example: "9F3B2C1D4E5A6B7C"

Request body

The request body is optional.

application/json

Field Type Requirement Description and constraints
$ object Optional body
Reference: #/components/schemas/ErrorGroupDetailRequest
start_time string Optional
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.
Format: date-time
Example: "2026-09-24T00:00:00Z"
end_time string Optional
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.
Format: date-time
Example: "2026-10-01T00:00:00Z"
environment string Optional
Only count spans from this environment, such as prod or test. Omit it to include every environment.
Example: "prod"
limit integer Optional
Most recent failures to return in occurrences. Values above 500 are capped at 500.
Default: 50
Minimum: 1
Maximum: 500
Example: 20

OpenAPI request schema

{
  "$ref": "#/components/schemas/ErrorGroupDetailRequest"
}
Example
JSON
{ "start_time": "2026-09-30T00:00:00Z", "end_time": "2026-10-01T00:00:00Z", "limit": 20 }

Responses

200

The error group.

application/json

Field Type Requirement Description and constraints
$ object and object Body
Reference: #/components/schemas/ErrorGroupDetail
$ (allOf 1) object Schema variant
Failed spans that share one fingerprint.
Reference: #/components/schemas/ErrorGroup
$ (allOf 1).fingerprint string Required in parent
Error group ID: a hash of error class, provider, endpoint and status code. 16 uppercase hex characters.
Example: "9F3B2C1D4E5A6B7C"
$ (allOf 1).title string Required in parent
Readable name: error class, provider and endpoint, and status code.
Example: "provider_rate_limit · openai chat/completions · 429"
$ (allOf 1).error_class string Required in parent
Normalized cause of the failure, assigned when the span is stored.
Reference: #/components/schemas/ErrorClass
Allowed: "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 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"
$ (allOf 1).level string Required in parent
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.
Allowed: "none", "ops_log", "ops_page"
Example: "ops_page"
$ (allOf 1).provider string Required in parent
Provider ID.
Example: "openai"
$ (allOf 1).endpoint string Required in parent
Upstream operation, such as chat/completions, responses or embeddings.
Example: "chat/completions"
$ (allOf 1).status integer Required in parent
HTTP status code.
Example: 429
$ (allOf 1).count integer Required in parent
Failed spans in the group in the time range.
Example: 318
$ (allOf 1).first_seen string Required in parent
First failure in the range. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T02:14:51.004112"
$ (allOf 1).last_seen string Required in parent
Latest failure in the range. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T23:58:12.771045"
$ (allOf 1).affected_customers integer Required in parent
Distinct customer_identifier values among the failures. Spans without one count as one value.
Example: 41
$ (allOf 1).affected_models integer Required in parent
Distinct models among the failures.
Example: 2
$ (allOf 1).resolution string Required in parent
Triage state. Groups you haven’t triaged are unresolved.
Reference: #/components/schemas/ErrorResolutionStatus
Allowed: "unresolved", "resolved", "ignored"
Example: "unresolved"
$ (allOf 2) object Schema variant
-
$ (allOf 2).occurrences array<object> Required in parent
Most recent failures in the group, newest first.
$ (allOf 2).occurrences[] object Array item
Reference: #/components/schemas/ErrorGroupOccurrence
$ (allOf 2).occurrences[].unique_id string Required in parent
Span ID. Get a span returns its full request, response and error message.
Example: "1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a"
$ (allOf 2).occurrences[].model string Required in parent
Example: "gpt-4o"
$ (allOf 2).occurrences[].status string Required in parent
Span status, such as failed.
Example: "failed"
$ (allOf 2).occurrences[].status_code integer Required in parent
HTTP status code.
Example: 429
$ (allOf 2).occurrences[].customer_identifier string Required in parent
Customer the span belongs to, if set.
Example: "acme-corp"
$ (allOf 2).occurrences[].environment string Required in parent
Example: "prod"
$ (allOf 2).occurrences[].timestamp string Required in parent
When the span failed. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T23:58:12.771045"

OpenAPI response schema

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

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

The group has no failures in the time range.

application/json

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

OpenAPI response schema

{
  "type": "object",
  "required": [
    "error",
    "fingerprint"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "fingerprint": {
      "type": "string"
    }
  }
}
Example
JSON
{ "error": "issue not found in window", "fingerprint": "9F3B2C1D4E5A6B7C" }

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