KEkeywordsai
Error Groups

Get error signals over time

Changed on

Returns failed spans per time bucket, split by a field such as error class, provider or error group. Reads spans directly, so range edges are exact.

post/api/pulses/errors/timeseries/

Request

  • Base URL
    https://api.respan.ai
  • URL
    https://api.respan.ai/api/pulses/errors/timeseries/
  • 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.

granularity'minute' | 'hour' | 'day' | 'week'

Bucket size.

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

Field to group by. issue groups by error group fingerprint, provider by provider ID, and status by HTTP 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'

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",
  "granularity": "hour",
  "group_by": "error_class",
  "error_class": "provider_rate_limit",
  "fault_domain": "provider",
  "provider": "openai",
  "status": 429,
  "filters": {
    "fault_domain": {
      "operator": "",
      "value": [
        "provider",
        "respan"
      ]
    }
  }
}

Response

Failed spans per bucket.

granularity'minute' | 'hour' | 'day' | 'week' required
group_by'customer_identifier' | 'deployment_name' | 'endpoint' | 'error_class' | 'fault_domain' | 'issue' | 'model' | 'provider' | 'status' required

Example response

{
  "granularity": "hour",
  "group_by": "error_class",
  "series": [
    {
      "bucket": "2026-09-30T14:00:00",
      "count": 27
    }
  ]
}

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_getErrorTimeSeries removed and replaced with getErrorTimeSeries

    • info

      api tag Error Groups added

    • info

      api tag errorGroups removed

  • b830b79cfd52Revision changes
    • info

      endpoint added