---
title: "Get error signals over time"
method: POST
path: "/api/pulses/errors/timeseries/"
tags: ["Error Groups"]
---

# Get error signals over time

`POST /api/pulses/errors/timeseries/`

## Request

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

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.

## Request body

- ErrorTimeSeriesRequest: 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.
  - `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.
  - `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`

Failed spans per bucket.

- ErrorTimeSeries
  - `granularity` 'minute' | 'hour' | 'day' | 'week', required
  - `group_by` 'customer_identifier' | 'deployment_name' | 'endpoint' | 'error_class' | 'fault_domain' | 'issue' | 'model' | 'provider' | 'status', required
  - `series` ErrorTimeSeriesPoint[], required: Points ordered by `bucket`. Buckets with no failures are missing.
    - `bucket` string, required: Start of the bucket. A date (`YYYY-MM-DD`) for `week` buckets. UTC, ISO 8601 without a timezone suffix.
    - `series` union, required: Value of the `group_by` field: an integer for `status`, else a string. Missing values are an empty string.
      - string
      - integer
    - `count` integer, required: Failed spans in the bucket for this value.

## Other responses

- `400`: Invalid `granularity`, `group_by` or `filters`.
- `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/timeseries/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)