KEkeywordsai
Error Groups

Get an error group

Changed on

Returns one error group's counts, first and last seen, reach and triage state in a time range, with its most recent failed spans.

post/api/pulses/errors/{fingerprint}/

Request

  • Base URL
    https://api.respan.ai
  • URL
    https://api.respan.ai/api/pulses/errors/{fingerprint}/
  • Auth
    HTTP bearer

Path parameters

fingerprintstring required

Error group fingerprint from List error groups: 16 uppercase hex characters, case-sensitive.

Request body

start_timestring date-time

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.

end_timestring date-time

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.

environmentstring

Only count spans from this environment, such as prod or test. Omit it to include every environment.

limitinteger

Most recent failures to return in occurrences. Values above 500 are capped at 500.

Example request

{
  "start_time": "2026-09-24T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "environment": "prod",
  "limit": 20
}

Response

The error group.

fingerprintstring required

Error group ID: a hash of error class, provider, endpoint and status code. 16 uppercase hex characters.

titlestring required

Readable name: error class, provider and endpoint, and status code.

error_class'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' required

Normalized cause of the failure, assigned when the span is stored.

fault_domain'user' | 'respan' | 'provider' | 'none' required

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).

level'none' | 'ops_log' | 'ops_page' required

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.

providerstring required

Provider ID.

endpointstring required

Upstream operation, such as chat/completions, responses or embeddings.

statusinteger required

HTTP status code.

countinteger required

Failed spans in the group in the time range.

first_seenstring required

First failure in the range. UTC, ISO 8601 without a timezone suffix.

last_seenstring required

Latest failure in the range. UTC, ISO 8601 without a timezone suffix.

affected_customersinteger required

Distinct customer_identifier values among the failures. Spans without one count as one value.

affected_modelsinteger required

Distinct models among the failures.

resolution'unresolved' | 'resolved' | 'ignored' required

Triage state. Groups you haven't triaged are unresolved.

Example response

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

Changes

  • c30bcb383ee8Revision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • info

      api operation id errorGroups_retrieveErrorGroup removed and replaced with retrieveErrorGroup

    • info

      api tag Error Groups added

    • info

      api tag errorGroups removed

    • info

      added subschema #2 to the response body allOf list for the response status

  • b830b79cfd52Revision changes
    • info

      endpoint added