Delete traces in 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.
Authentication
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.
Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.
Query parameters
Start of time range (ISO 8601). Defaults to one hour before end_time when omitted.
End of time range (ISO 8601). Defaults to now when omitted.
Request
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:
{
"trace_unique_id": {"operator": "in", "value": ["trace-01", "trace-02"]}
}
Response
Item-level failures, keyed by zero-based input index.
Human-readable deletion result.