API ReferenceTraces

List traces

Retrieve a paginated list of traces matching your filters. Supports the filter payload documented in the Filters API. Metadata keys beginning with _ are reserved for platform use and are omitted from customer-facing span and trace responses, so they do not round-trip through read APIs.

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

pageintegerOptionalDefaults to 1
Page number.
page_sizeintegerOptional<=1000Defaults to 50

Results per page (max 1000).

sort_bystringOptionalDefaults to -timestamp

Field to sort by. Prefix - for descending. Common values include -timestamp, -total_cost, -duration, -total_tokens, and -error_count.

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.
filtersobjectOptional

Filter criteria. See Filters API Reference for operator syntax.

Response

Paginated list of traces.
countinteger
Total number of matching traces.
resultslist of objects
Current page of traces.
nextstring or nullOptional
URL for the next page of results.
previousstring or nullOptional
URL for the previous page of results.

Errors

400
Bad Request Error
401
Unauthorized Error
413
Content Too Large Error
429
Too Many Requests Error
500
Internal Server Error