API ReferenceTraces

Bulk delete traces

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.

Authentication

AuthorizationBearer

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.

OR
AuthorizationBearer

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

Query parameters

start_timedatetimeOptional

Start of time range (ISO 8601). Defaults to one hour before end_time when omitted.

end_timedatetimeOptional

End of time range (ISO 8601). Defaults to now when omitted.

environmentstringOptional
Filter by environment.

Request

This endpoint expects an object.
filtersobjectRequired

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.

Response

Traces were matched and submitted for asynchronous deletion.
success_countinteger>=0
Number of items successfully processed.
error_countinteger>=0
Number of items that failed.
errorslist of objects

Item-level failures, keyed by zero-based input index.

deleted_countinteger>=0
Number of resources matched and processed for deletion.
messagestring

Human-readable deletion result.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error