---
title: "Bulk delete traces"
method: POST
path: "/api/traces/bulk/"
tags: ["traces"]
---

# Bulk delete traces

`POST /api/traces/bulk/`

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. The current server ignores unknown fields and invalid operators, which can broaden the deletion selection, so validate filters carefully before sending them. 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

## Headers

- `Authorization` string, required

## Request body

- object
  - `filters` TraceBulkDeleteFilters, required — Non-empty trace-level filters. The named fields below are supported, along with dynamic `metadata__<key>` fields. Environment and time filters in this object are ANDed with the query-parameter/default window. Do not send other field names: the current server ignores unknown fields instead of rejecting them, which can broaden a delete request.
    - `trace_unique_id` TraceFilterCondition — A trace filter condition. Use `is` for an exact value or `in` for any value in a list.
      - `operator` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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` 'is' | '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, 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 bulk result envelope plus delete-specific fields.
  - `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`, or `filters` is empty.
- `401` — Unauthorized - Missing or invalid authentication
- `403` — Forbidden - The caller cannot delete traces
- `422` — The filters matched more than 1,000 traces. Narrow the filters and retry.
- `429` — Rate limit exceeded.
- `500` — Internal Server Error

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)