RErespan
Error Groups

Get errors by dimension

Changed on

Splits failed spans by a field, such as model or customer. The signals panel narrows by a group's error_class, provider and status for its "Errors by model" and "Errors by customer" splits; groups that differ only by endpoint count together.

post/api/pulses/errors/grouped/

Request

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

Request body

group_by'customer_identifier' | 'deployment_name' | 'endpoint' | 'error_class' | 'fault_domain' | 'issue' | 'model' | 'provider' | 'status' required

Field to group by. issue groups by error group fingerprint, provider by provider ID, and status by HTTP status code.

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

Maximum groups to return. Values above 100 are capped at 100.

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

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

Response

Failed spans per group.

group_by'customer_identifier' | 'deployment_name' | 'endpoint' | 'error_class' | 'fault_domain' | 'issue' | 'model' | 'provider' | 'status' required

Example response

{
  "group_by": "model",
  "groups": [
    {
      "count": 212
    }
  ]
}

Changes

  • c30bcb383ee8Revision changes
    • breaking

      request body became required

    • 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_getErrorBreakdown removed and replaced with getErrorBreakdown

    • info

      api tag Error Groups added

    • info

      api tag errorGroups removed

  • b830b79cfd52Revision changes
    • info

      endpoint added