List spans
Filter on span fields with filters, and sort by evaluator scores. 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.
Start of time range (ISO 8601).
End of time range (ISO 8601).
Filter by environment (prod or test).
Filter by span/log type. Use values like chat, completion, or response to focus on model-inference spans; omitting this can also return non-chat span/log rows such as legacy text logs.
Comma-separated list of fields to include in each span. Reduces response size.
Request
Each key is a field to filter on, and each value is a condition: {"<field>": {"operator": "<operator>", "value": [...]}}. A span 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:
unique_id,trace_unique_id,span_unique_id,span_parent_id,span_name,span_workflow_name,thread_identifier,customer_identifier,customer_email,custom_identifier,group_identifier,evaluation_identifier,organization_key_id,prompt_id,prompt_name,prompt_version_number,model,provider_id,deployment_name,log_type,log_method,status,status_code,environment,error_class,error_code,error_message,error_fingerprint,cache_key,note- True or false:
stream,has_tool_calls,cache_bit,used_custom_credential,positive_feedback - Numbers:
cost,latency,time_to_first_token,tokens_per_second,routing_time,prompt_tokens,completion_tokens,total_request_tokens,prompt_cache_hit_tokens,prompt_cache_creation_tokens. The aliasestotal_cost,input_tokens,output_tokensandtotal_tokensalso work, and so doestrace_idfortrace_unique_id. metadata__<key>: a custom metadata value. Values are strings, and spans without the key never match, even withnot.scores__<evaluator_id>: an evaluator's numeric score, with"",not,in,not_in,lt,lte,gtorgte.is_root_span([true]or[false]),fault_domain(user,respanorprovider), andbehaviors(spans where the named behaviors fired, when span behaviors are on).
Unsupported fields return a 400 error.
Example:
{
"model": {"operator": "in", "value": ["gpt-5.5", "claude-sonnet-4-5-20250929"]},
"cost": {"operator": "gte", "value": [0.01]},
"metadata__plan": {"operator": "", "value": ["pro"]}
}
Response
Number of results on this page, not the total. Request pages until next is null to get every result.