---
title: "List error groups"
method: POST
path: "/api/pulses/errors/"
tags: ["Error Groups"]
---

# List error groups

`POST /api/pulses/errors/`

## Request

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

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.

## Request body

- ErrorGroupListRequest: When a flat key and `filters` narrow the same field, `filters` wins.
  - `start_time` string, 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_time` string, 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.
  - `environment` string: 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.
  - `provider` string: Only errors from this provider ID.
  - `status` integer: Only errors with this HTTP status code.
  - `filters` ErrorGroupFilters: Narrow the errors with the same filter shape as the Logs filter bar. Only these four keys are accepted; any other key is a 400.
    - `error_class` ErrorGroupFilterCondition
      - `operator` '' | 'not' | 'in' | 'empty' | 'not_empty': `""` (is any of), `not` (is none of), `in`, `empty` or `not_empty`. Allowed operators per key: `error_class` and `fault_domain` take `""`, `not`, `in`; `provider_id` takes `""`, `not`, `empty`, `not_empty`; `status_code` takes `""`, `not`.
      - `value` union: One value or a list. Required unless `operator` is `empty` or `not_empty`.
        - string
        - integer
        - union[]
          - union
            - string
            - integer
    - `fault_domain` ErrorGroupFilterCondition
      - `operator` '' | 'not' | 'in' | 'empty' | 'not_empty': `""` (is any of), `not` (is none of), `in`, `empty` or `not_empty`. Allowed operators per key: `error_class` and `fault_domain` take `""`, `not`, `in`; `provider_id` takes `""`, `not`, `empty`, `not_empty`; `status_code` takes `""`, `not`.
      - `value` union: One value or a list. Required unless `operator` is `empty` or `not_empty`.
        - string
        - integer
        - union[]
          - union
            - string
            - integer
    - `provider_id` ErrorGroupFilterCondition
      - `operator` '' | 'not' | 'in' | 'empty' | 'not_empty': `""` (is any of), `not` (is none of), `in`, `empty` or `not_empty`. Allowed operators per key: `error_class` and `fault_domain` take `""`, `not`, `in`; `provider_id` takes `""`, `not`, `empty`, `not_empty`; `status_code` takes `""`, `not`.
      - `value` union: One value or a list. Required unless `operator` is `empty` or `not_empty`.
        - string
        - integer
        - union[]
          - union
            - string
            - integer
    - `status_code` ErrorGroupFilterCondition
      - `operator` '' | 'not' | 'in' | 'empty' | 'not_empty': `""` (is any of), `not` (is none of), `in`, `empty` or `not_empty`. Allowed operators per key: `error_class` and `fault_domain` take `""`, `not`, `in`; `provider_id` takes `""`, `not`, `empty`, `not_empty`; `status_code` takes `""`, `not`.
      - `value` union: One value or a list. Required unless `operator` is `empty` or `not_empty`.
        - string
        - integer
        - union[]
          - union
            - string
            - integer

## Response `200`

Error groups for the range.

- ErrorGroupList
  - `issues` ErrorGroup[], required: Up to 200 error groups, most failures first. There is no pagination.
    - `fingerprint` string, required: Error group ID: a hash of error class, provider, endpoint and status code. 16 uppercase hex characters.
    - `title` string, 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.
    - `provider` string, required: Provider ID.
    - `endpoint` string, required: Upstream operation, such as `chat/completions`, `responses` or `embeddings`.
    - `status` integer, required: HTTP status code.
    - `count` integer, required: Failed spans in the group in the time range.
    - `first_seen` string, required: First failure in the range. UTC, ISO 8601 without a timezone suffix.
    - `last_seen` string, required: Latest failure in the range. UTC, ISO 8601 without a timezone suffix.
    - `affected_customers` integer, required: Distinct `customer_identifier` values among the failures. Spans without one count as one value.
    - `affected_models` integer, required: Distinct models among the failures.
    - `resolution` 'unresolved' | 'resolved' | 'ignored', required: Triage state. Groups you haven't triaged are `unresolved`.
  - `total_issues` integer, required: Error groups in the range, including any past the first 200.
  - `total_errors` integer, required: Failed spans across all groups in the range.

## Other responses

- `400`: A `filters` key is not supported, or its operator or value is invalid. The body maps the key to its error.
- `403`: Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:read` (Read access does).
- `429`: Rate limited. This endpoint allows 60 requests per minute per organization.

## Changes

- **2026-10-21** `c30bcb383ee8`: 20 breaking, 3 info
  - added `#/components/schemas/ErrorClass` to the `error_class` request property `allOf` list
  - removed the enum value `client_cancelled` of the request property `error_class`
  - removed the enum value `network_transient` of the request property `error_class`
  - removed the enum value `provider_down` of the request property `error_class`
  - …19 more
- **2026-10-02** `b830b79cfd52`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/pulses/errors/post.md)

---

[API](https://skmtc.dev/respan/apis/respan-api.md) - [All operations](https://skmtc.dev/respan/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/respan/apis/respan-api/revisions/900841387635?raw)