KEkeywordsai
Error Groups

List error groups

Changed on

Lists failed spans grouped by fingerprint, most failures first, with each group's reach and triage state. Counts come from a rollup refreshed every 10 minutes, so the range is widened to whole hours.

post/api/pulses/errors/

Request

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

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.

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'

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

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

Only errors with this fault. none selects client cancellations.

providerstring

Only errors from this provider ID.

statusinteger

Only errors with this HTTP status code.

Example request

{
  "start_time": "2026-09-24T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "environment": "prod",
  "error_class": "provider_rate_limit",
  "fault_domain": "provider",
  "provider": "openai",
  "status": 429,
  "filters": {
    "fault_domain": {
      "operator": "",
      "value": [
        "provider",
        "respan"
      ]
    }
  }
}

Response

Error groups for the range.

total_issuesinteger required

Error groups in the range, including any past the first 200.

total_errorsinteger required

Failed spans across all groups in the range.

Example response

{
  "issues": [
    {
      "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"
    }
  ],
  "total_issues": 12,
  "total_errors": 1405
}

Changes

  • c30bcb383ee8Revision changes
    • breaking

      added to the request property allOf list

    • breaking

      removed the enum value client_cancelled of the request property

    • breaking

      removed the enum value network_transient of the request property

    • breaking

      removed the enum value provider_down of the request property

    • breaking

      removed the enum value provider_overloaded of the request property

    • breaking

      removed the enum value provider_rate_limit of the request property

    • breaking

      removed the enum value provider_timeout of the request property

    • breaking

      removed the enum value respan_config of the request property

    • breaking

      removed the enum value respan_internal of the request property

    • breaking

      removed the enum value respan_managed_auth of the request property

    • breaking

      removed the enum value respan_managed_billing of the request property

    • breaking

      removed the enum value unknown of the request property

    • breaking

      removed the enum value user_auth_byok of the request property

    • breaking

      removed the enum value user_content_policy of the request property

    • breaking

      removed the enum value user_context_window of the request property

    • breaking

      removed the enum value user_invalid_request of the request property

    • breaking

      removed the enum value user_payload_too_large of the request property

    • breaking

      removed the enum value user_quota of the request property

    • breaking

      removed the enum value user_rate_limit of the request property

    • breaking

      the request property type changed from string to no type

    • info

      api operation id errorGroups_listErrorGroups removed and replaced with listErrorGroups

    • info

      api tag Error Groups added

    • info

      api tag errorGroups removed

  • b830b79cfd52Revision changes
    • info

      endpoint added