---
title: "Delete traces in bulk"
method: POST
path: "/api/traces/bulk/"
tags: ["Traces"]
---

# Delete traces in bulk

`POST /api/traces/bulk/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/traces/bulk/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Delete traces matching a non-empty filter object. The endpoint resolves at most 1,000 trace IDs per request; requests matching more are rejected with `422`. Use the query parameters for the canonical environment and time window; the same fields in the body only narrow that window. Only the documented filter fields and `metadata__<key>` are supported. Unknown fields and invalid operators return `400` before anything is deleted. ClickHouse deletion is asynchronous, so `success_count` and `deleted_count` report traces submitted for deletion, not confirmation that every row has already disappeared. Rate limit: 10 requests per minute per organization and exact endpoint path for API-key calls (shared across API keys), and per user and exact endpoint path for JWT calls.

## Query parameters

- `start_time` string, date-time
- `end_time` string, date-time
- `environment` string

## Request body

- object
  - `filters` TraceBulkDeleteFilters, required: Required. Selects the traces to delete. Each key is a field to filter on, and each value is a condition: `{"<field>": {"operator": "<operator>", "value": [...]}}`. A trace must match every condition. To set two conditions on one field, such as a range, pass a list of conditions. **Operators:** `""` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `""` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[""]`. **Fields:** `trace_unique_id`, `customer_identifier`, `environment`, `start_time`, `end_time`, `span_count`, `llm_call_count`, `error_count`, `total_cost`, `total_prompt_tokens`, `total_completion_tokens`, `total_tokens`, and `metadata__<key>` (values are strings). Here `environment`, `start_time` and `end_time` only narrow the window set by the query parameters. Unsupported fields or operators return a 400 error, and nothing is deleted. **Example:** ```json { "trace_unique_id": {"operator": "in", "value": ["trace-01", "trace-02"]} } ```
    - `trace_unique_id` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `unique_organization_id` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `environment` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `start_time` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `end_time` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `span_count` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `llm_call_count` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `total_cost` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `total_prompt_tokens` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `total_completion_tokens` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `total_tokens` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `error_count` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown
    - `customer_identifier` TraceFilterCondition: A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'notEmpty' | 'not_empty' | 'isnull': Comparison operator. If omitted or empty, exact matching is used.
      - `value` unknown[], required: One or more values used by the comparison.
        - unknown

## Response `200`

Traces were matched and submitted for asynchronous deletion.

- BulkDeleteResponse: Canonical result envelope for a bulk operation.
  - `success_count` integer, required: Number of items successfully processed.
  - `error_count` integer, required: Number of items that failed.
  - `errors` BulkItemError[], required: Item-level failures, keyed by zero-based input index.
    - `index` integer, required: Zero-based index of the failed item in the submitted array.
    - `error` string, required: Error message for the failed item.
  - `deleted_count` integer, required: Number of resources matched and processed for deletion.
  - `message` string, required: Human-readable deletion result.

## Other responses

- `400`: The request body is missing `filters`, `filters` is empty, or it uses an unknown field or invalid operator.
- `403`: The API key is missing, invalid or expired, or it can't delete traces.
- `422`: The filters matched more than 1,000 traces. Narrow the filters and retry.
- `429`: Rate limit exceeded.
- `500`: Internal Server Error

## Changes

- **2026-10-21** `c30bcb383ee8`: 20 breaking, 5 info
  - request body became required
  - the `filters/customer_identifier/value` request property's minItems was increased to `1`
  - the `filters/end_time/value` request property's minItems was increased to `1`
  - the `filters/environment/value` request property's minItems was increased to `1`
  - …21 more
- **2026-10-02** `b830b79cfd52`: 14 breaking, 28 info
  - removed the enum value `is` of the request property `filters/customer_identifier/operator`
  - removed the enum value `is` of the request property `filters/end_time/operator`
  - removed the enum value `is` of the request property `filters/environment/operator`
  - removed the enum value `is` of the request property `filters/error_count/operator`
  - …38 more
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `bulk-delete-traces` removed and replaced with `traces_bulkDeleteTraces`
- **2026-08-13** `4e064cf81dae`: 15 info
  - added the new optional `query` request parameter `end_time`
  - added the new optional `query` request parameter `environment`
  - added the new optional `query` request parameter `start_time`
  - added optional request body
  - …11 more

[Operation history](https://skmtc.dev/keywordsai/apis/respan-api/changes/api/traces/bulk/post.md)

---

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