---
title: "Delete traces in bulk"
description: "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."
---

<a id="playground-button:docs/apis/traces/delete-traces-in-bulk"></a>

**POST** `https://api.respan.ai/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. 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.

## Servers

`https://api.respan.ai` — Respan API Server

<a id="request.auth"></a>

## Authentication

<a id="request.auth.Authorization"></a>

### RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer &lt;RESPAN_API_KEY&gt;. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -&gt; Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: `bearer`; format: `Respan API key`.


```http
Authorization: Bearer $RESPAN_API_KEY
```


**Or:**

### DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: `bearer`; format: `Dashboard JWT`.


```http
Authorization: Bearer $RESPAN_DASHBOARD_JWT
```


<a id="request.query"></a>

## Query parameters


| Parameter | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| <a id="request.query.start_time"></a>`start_time` | `string` | Optional | Start of time range (ISO 8601). Defaults to one hour before `end_time` when omitted.<br />Format: `date-time`<br />Example: `"2025-01-01T00:00:00Z"` |
| <a id="request.query.end_time"></a>`end_time` | `string` | Optional | End of time range (ISO 8601). Defaults to now when omitted.<br />Format: `date-time`<br />Example: `"2025-01-31T23:59:59Z"` |
| <a id="request.query.environment"></a>`environment` | `string` | Optional | Filter by environment.<br />Example: `"prod"` |


<a id="request"></a>

## Request body

A request body is required.

### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Required body | — |
| <a id="request.body.filters"></a>`filters` | `object` | Required in parent | Required. Selects the traces to delete.<br /><br />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.<br /><br />**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 `[""]`.<br /><br />**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.<br /><br />**Example:**<br /><br />```json<br />{<br />  "trace_unique_id": {"operator": "in", "value": ["trace-01", "trace-02"]}<br />}<br />```<br />Reference: `#/components/schemas/TraceBulkDeleteFilters`<br />Minimum properties: `1`<br />Example: `{"customer_identifier":{"operator":"","value":["customer-123"]}}` |
| `filters.trace_unique_id` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.trace_unique_id.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.trace_unique_id.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.trace_unique_id.value[]` | `any` | Array item | — |
| `filters.unique_organization_id` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.unique_organization_id.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.unique_organization_id.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.unique_organization_id.value[]` | `any` | Array item | — |
| `filters.environment` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.environment.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.environment.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.environment.value[]` | `any` | Array item | — |
| `filters.start_time` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.start_time.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.start_time.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.start_time.value[]` | `any` | Array item | — |
| `filters.end_time` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.end_time.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.end_time.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.end_time.value[]` | `any` | Array item | — |
| `filters.span_count` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.span_count.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.span_count.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.span_count.value[]` | `any` | Array item | — |
| `filters.llm_call_count` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.llm_call_count.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.llm_call_count.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.llm_call_count.value[]` | `any` | Array item | — |
| `filters.total_cost` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.total_cost.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.total_cost.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.total_cost.value[]` | `any` | Array item | — |
| `filters.total_prompt_tokens` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.total_prompt_tokens.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.total_prompt_tokens.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.total_prompt_tokens.value[]` | `any` | Array item | — |
| `filters.total_completion_tokens` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.total_completion_tokens.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.total_completion_tokens.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.total_completion_tokens.value[]` | `any` | Array item | — |
| `filters.total_tokens` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.total_tokens.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.total_tokens.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.total_tokens.value[]` | `any` | Array item | — |
| `filters.error_count` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.error_count.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.error_count.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.error_count.value[]` | `any` | Array item | — |
| `filters.customer_identifier` | `object` | Optional | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.customer_identifier.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.customer_identifier.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.customer_identifier.value[]` | `any` | Array item | — |
| `filters.<key>` | `object` | Map value | A trace filter condition. Use `is` for an exact value or `in` for any value in a list.<br />Reference: `#/components/schemas/TraceFilterCondition`<br />Additional properties are not allowed<br />Example: `{"operator":"in","value":["trace-01","trace-02"]}` |
| `filters.<key>.operator` | `string` | Optional | Comparison operator. If omitted or empty, exact matching is used.<br />Allowed: `""`, `"not"`, `"in"`, `"not_in"`, `"lt"`, `"lte"`, `"gt"`, `"gte"`, `"contains"`, `"not_contains"`, `"icontains"`, `"startswith"`, `"not_startswith"`, `"endswith"`, `"not_endswith"`, `"empty"`, `"notEmpty"`, `"not_empty"`, `"isnull"`<br />Default: `` |
| `filters.<key>.value` | `array<any>` | Required in parent | One or more values used by the comparison.<br />Minimum items: `1` |
| `filters.<key>.value[]` | `any` | Array item | — |


<details class="api-schema-source">
<summary>OpenAPI request schema</summary>


```json
{
  "type": "object",
  "required": [
    "filters"
  ],
  "properties": {
    "filters": {
      "$ref": "#/components/schemas/TraceBulkDeleteFilters"
    }
  }
}
```

</details>

##### Delete traces for one customer


```json
{
  "filters": {
    "customer_identifier": {
      "operator": "",
      "value": [
        "customer-123"
      ]
    }
  }
}
```


##### Delete selected trace IDs


```json
{
  "filters": {
    "trace_unique_id": {
      "operator": "in",
      "value": [
        "trace-01",
        "trace-02"
      ]
    }
  }
}
```


## Examples

### Delete traces for one customer

#### Headers


```json
{
  "Authorization": "Bearer YOUR_RESPAN_API_KEY"
}
```


#### Query parameters


```json
{
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-01-31T23:59:59Z",
  "environment": "prod"
}
```


#### Request


```json
{
  "filters": {
    "customer_identifier": {
      "operator": "",
      "value": [
        "customer-123"
      ]
    }
  }
}
```


#### Response


```json
{
  "body": {
    "success_count": 42,
    "error_count": 0,
    "errors": [],
    "deleted_count": 42,
    "message": "Successfully deleted 42 traces"
  }
}
```


### Delete selected trace IDs

#### Headers


```json
{
  "Authorization": "Bearer YOUR_RESPAN_API_KEY"
}
```


#### Query parameters


```json
{
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-01-31T23:59:59Z",
  "environment": "prod"
}
```


#### Request


```json
{
  "filters": {
    "trace_unique_id": {
      "operator": "in",
      "value": [
        "trace-01",
        "trace-02"
      ]
    }
  }
}
```


#### Response


```json
{
  "body": {
    "success_count": 42,
    "error_count": 0,
    "errors": [],
    "deleted_count": 42,
    "message": "Successfully deleted 42 traces"
  }
}
```


<a id="response"></a>

## Responses

### 200

Traces were matched and submitted for asynchronous deletion.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object and object` | Body | Canonical bulk result envelope plus delete-specific fields.<br />Reference: `#/components/schemas/BulkDeleteResponse` |
| `$ (allOf 1)` | `object` | Schema variant | Canonical result envelope for a bulk operation.<br />Reference: `#/components/schemas/BulkOperationResponse`<br />Example: `{"success_count":1,"error_count":0,"errors":[]}` |
| <a id="response.body.success_count"></a>`$ (allOf 1).success_count` | `integer` | Required in parent | Number of items successfully processed.<br />Minimum: `0` |
| <a id="response.body.error_count"></a>`$ (allOf 1).error_count` | `integer` | Required in parent | Number of items that failed.<br />Minimum: `0` |
| <a id="response.body.errors"></a>`$ (allOf 1).errors` | `array<object>` | Required in parent | Item-level failures, keyed by zero-based input index. |
| `$ (allOf 1).errors[]` | `object` | Array item | An item that failed during a bulk operation. `index` is zero-based and identifies the corresponding item in the request array.<br />Reference: `#/components/schemas/BulkItemError` |
| `$ (allOf 1).errors[].index` | `integer` | Required in parent | Zero-based index of the failed item in the submitted array.<br />Minimum: `0` |
| `$ (allOf 1).errors[].error` | `string` | Required in parent | Error message for the failed item. |
| `$ (allOf 2)` | `object` | Schema variant | — |
| <a id="response.body.deleted_count"></a>`$ (allOf 2).deleted_count` | `integer` | Required in parent | Number of resources matched and processed for deletion.<br />Minimum: `0` |
| <a id="response.body.message"></a>`$ (allOf 2).message` | `string` | Required in parent | Human-readable deletion result. |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "$ref": "#/components/schemas/BulkDeleteResponse"
}
```

</details>

##### Matching traces submitted for deletion


```json
{
  "success_count": 42,
  "error_count": 0,
  "errors": [],
  "deleted_count": 42,
  "message": "Successfully deleted 42 traces"
}
```


##### No matching traces


```json
{
  "success_count": 0,
  "error_count": 0,
  "errors": [],
  "deleted_count": 0,
  "message": "No traces matched the given filters"
}
```


<a id="response.error"></a>

### 400

The request body is missing `filters`, `filters` is empty, or it uses an unknown field or invalid operator.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `filters` | `array<string>` | Required in parent | — |
| `filters[]` | `string` | Array item | — |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "required": [
    "filters"
  ],
  "properties": {
    "filters": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}
```

</details>

##### Missing filters field


```json
{
  "filters": [
    "This field is required."
  ]
}
```


##### Empty filters object


```json
{
  "filters": [
    "Must be a non-empty filter dict."
  ]
}
```


### 403

The API key is missing, invalid or expired, or it can't delete traces.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `detail` | `string` | Required in parent | — |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
```

</details>

##### Example


```json
{
  "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
```


### 422

The filters matched more than 1,000 traces. Narrow the filters and retry.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `detail` | `string` | Required in parent | — |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
```

</details>

##### Example


```json
{
  "detail": "Cannot process more than 1000 items at once."
}
```


### 429

Rate limit exceeded.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `detail` | `string` | Required in parent | — |
| `retry_after` | `integer` | Optional | Seconds to wait before retrying.<br />Minimum: `0` |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    },
    "retry_after": {
      "type": "integer",
      "minimum": 0,
      "description": "Seconds to wait before retrying."
    }
  }
}
```

</details>

##### Example


```json
{
  "detail": "Rate limit exceeded",
  "retry_after": 30
}
```


### 500

Internal Server Error

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `error` | `string` | Optional | Example: `"Internal server error"` |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "example": "Internal server error"
    }
  }
}
```

</details>

## OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

<!-- openapi-operation:start -->
<details class="api-schema-source">
<summary>OpenAPI operation</summary>


```json
{
  "summary": "Delete traces in bulk",
  "operationId": "bulkDeleteTraces",
  "tags": [
    "Traces"
  ],
  "description": "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.",
  "parameters": [
    {
      "name": "start_time",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "Start of time range (ISO 8601). Defaults to one hour before `end_time` when omitted.",
      "example": "2025-01-01T00:00:00Z"
    },
    {
      "name": "end_time",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "End of time range (ISO 8601). Defaults to now when omitted.",
      "example": "2025-01-31T23:59:59Z"
    },
    {
      "name": "environment",
      "in": "query",
      "schema": {
        "type": "string"
      },
      "description": "Filter by environment.",
      "example": "prod"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "filters"
          ],
          "properties": {
            "filters": {
              "$ref": "#/components/schemas/TraceBulkDeleteFilters"
            }
          }
        },
        "examples": {
          "byCustomer": {
            "summary": "Delete traces for one customer",
            "value": {
              "filters": {
                "customer_identifier": {
                  "operator": "",
                  "value": [
                    "customer-123"
                  ]
                }
              }
            }
          },
          "byTraceIds": {
            "summary": "Delete selected trace IDs",
            "value": {
              "filters": {
                "trace_unique_id": {
                  "operator": "in",
                  "value": [
                    "trace-01",
                    "trace-02"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Traces were matched and submitted for asynchronous deletion.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BulkDeleteResponse"
          },
          "examples": {
            "success": {
              "summary": "Matching traces submitted for deletion",
              "value": {
                "success_count": 42,
                "error_count": 0,
                "errors": [],
                "deleted_count": 42,
                "message": "Successfully deleted 42 traces"
              }
            },
            "noMatches": {
              "summary": "No matching traces",
              "value": {
                "success_count": 0,
                "error_count": 0,
                "errors": [],
                "deleted_count": 0,
                "message": "No traces matched the given filters"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The request body is missing `filters`, `filters` is empty, or it uses an unknown field or invalid operator.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "filters"
            ],
            "properties": {
              "filters": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "examples": {
            "missingFilters": {
              "summary": "Missing filters field",
              "value": {
                "filters": [
                  "This field is required."
                ]
              }
            },
            "emptyFilters": {
              "summary": "Empty filters object",
              "value": {
                "filters": [
                  "Must be a non-empty filter dict."
                ]
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The API key is missing, invalid or expired, or it can't delete traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    },
    "422": {
      "description": "The filters matched more than 1,000 traces. Narrow the filters and retry.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Cannot process more than 1000 items at once."
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              },
              "retry_after": {
                "type": "integer",
                "minimum": 0,
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "example": {
            "detail": "Rate limit exceeded",
            "retry_after": 30
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "example": "Internal server error"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ],
  "x-fern-examples": [
    {
      "name": "Delete traces for one customer",
      "query-parameters": {
        "start_time": "2025-01-01T00:00:00Z",
        "end_time": "2025-01-31T23:59:59Z",
        "environment": "prod"
      },
      "request": {
        "filters": {
          "customer_identifier": {
            "operator": "",
            "value": [
              "customer-123"
            ]
          }
        }
      },
      "response": {
        "body": {
          "success_count": 42,
          "error_count": 0,
          "errors": [],
          "deleted_count": 42,
          "message": "Successfully deleted 42 traces"
        }
      },
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    },
    {
      "name": "Delete selected trace IDs",
      "query-parameters": {
        "start_time": "2025-01-01T00:00:00Z",
        "end_time": "2025-01-31T23:59:59Z",
        "environment": "prod"
      },
      "request": {
        "filters": {
          "trace_unique_id": {
            "operator": "in",
            "value": [
              "trace-01",
              "trace-02"
            ]
          }
        }
      },
      "response": {
        "body": {
          "success_count": 42,
          "error_count": 0,
          "errors": [],
          "deleted_count": 42,
          "message": "Successfully deleted 42 traces"
        }
      },
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    }
  ]
}
```

</details>
<!-- openapi-operation:end -->

<!-- openapi-path-item:start -->
<details class="api-schema-source">
<summary>OpenAPI path metadata</summary>


```json
{}
```

</details>
<!-- openapi-path-item:end -->

<!-- openapi-components:start -->
<details class="api-schema-source">
<summary>Referenced OpenAPI components</summary>


````json
{
  "schemas": {
    "BulkDeleteResponse": {
      "description": "Canonical bulk result envelope plus delete-specific fields.",
      "allOf": [
        {
          "$ref": "#/components/schemas/BulkOperationResponse"
        },
        {
          "type": "object",
          "required": [
            "deleted_count",
            "message"
          ],
          "properties": {
            "deleted_count": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of resources matched and processed for deletion."
            },
            "message": {
              "type": "string",
              "description": "Human-readable deletion result."
            }
          }
        }
      ]
    },
    "BulkItemError": {
      "type": "object",
      "description": "An item that failed during a bulk operation. `index` is zero-based and identifies the corresponding item in the request array.",
      "required": [
        "index",
        "error"
      ],
      "properties": {
        "index": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index of the failed item in the submitted array."
        },
        "error": {
          "type": "string",
          "description": "Error message for the failed item."
        }
      }
    },
    "BulkOperationResponse": {
      "type": "object",
      "description": "Canonical result envelope for a bulk operation.",
      "required": [
        "success_count",
        "error_count",
        "errors"
      ],
      "properties": {
        "success_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of items successfully processed."
        },
        "error_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of items that failed."
        },
        "errors": {
          "type": "array",
          "description": "Item-level failures, keyed by zero-based input index.",
          "items": {
            "$ref": "#/components/schemas/BulkItemError"
          }
        }
      },
      "example": {
        "success_count": 1,
        "error_count": 0,
        "errors": []
      }
    },
    "TraceBulkDeleteFilters": {
      "type": "object",
      "description": "Required. Selects the traces to delete.\n\nEach 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.\n\n**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 `[\"\"]`.\n\n**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.\n\n**Example:**\n\n```json\n{\n  \"trace_unique_id\": {\"operator\": \"in\", \"value\": [\"trace-01\", \"trace-02\"]}\n}\n```",
      "minProperties": 1,
      "properties": {
        "trace_unique_id": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "unique_organization_id": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "environment": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "start_time": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "end_time": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "span_count": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "llm_call_count": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "total_cost": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "total_prompt_tokens": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "total_completion_tokens": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "total_tokens": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "error_count": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        },
        "customer_identifier": {
          "$ref": "#/components/schemas/TraceFilterCondition"
        }
      },
      "additionalProperties": {
        "$ref": "#/components/schemas/TraceFilterCondition"
      },
      "example": {
        "customer_identifier": {
          "operator": "",
          "value": [
            "customer-123"
          ]
        }
      }
    },
    "TraceFilterCondition": {
      "type": "object",
      "description": "A trace filter condition. Use `is` for an exact value or `in` for any value in a list.",
      "required": [
        "value"
      ],
      "properties": {
        "operator": {
          "type": "string",
          "description": "Comparison operator. If omitted or empty, exact matching is used.",
          "default": "",
          "enum": [
            "",
            "not",
            "in",
            "not_in",
            "lt",
            "lte",
            "gt",
            "gte",
            "contains",
            "not_contains",
            "icontains",
            "startswith",
            "not_startswith",
            "endswith",
            "not_endswith",
            "empty",
            "notEmpty",
            "not_empty",
            "isnull"
          ]
        },
        "value": {
          "type": "array",
          "minItems": 1,
          "description": "One or more values used by the comparison.",
          "items": {}
        }
      },
      "additionalProperties": false,
      "example": {
        "operator": "in",
        "value": [
          "trace-01",
          "trace-02"
        ]
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}
````

</details>
<!-- openapi-components:end -->
