List traces
Returns traces matching the Filters API payload, with pagination. Metadata keys beginning with _ are reserved for platform use and omitted from span and trace read responses.
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
Results per page (max 1000).
Field to sort by. Prefix - for descending. Common values include -timestamp, -total_cost, -duration, -total_tokens, and -error_count.
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
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:
trace_unique_id,name(the workflow name),customer_identifier,environment,organization_key_id,trace_group_identifier,session_identifier,root_span_unique_id,span_count,llm_call_count,error_count,total_cost,total_prompt_tokens,total_completion_tokens,total_request_tokens,duration(seconds), andmetadata__<key>(values are strings). - Span fields, which match a trace when any of its spans matches:
span_unique_id,span_name,span_workflow_name,span_parent_id,model,provider_id,deployment_name,prompt_id,prompt_name,prompt_version_number,log_type,log_method,status,status_code,error_class,error_fingerprint,cost,latency,time_to_first_token,tokens_per_second,routing_time,prompt_tokens,completion_tokens,prompt_cache_hit_tokens,prompt_cache_creation_tokens.
Unsupported fields, such as total_tokens, return a 400 error.
Example:
{
"total_cost": {"operator": "gte", "value": [0.05]},
"model": {"operator": "", "value": ["gpt-5.5"]}
}
Response
Number of results on this page, not the total. Request pages until next is null to get every result.