List traces

POST

https://api.respan.ai/api/traces/list/

POST

/api/traces/list/

$ curl -X POST "https://api.respan.ai/api/traces/list/?page=1&page_size=50&sort_by=-total_cost&start_time=2025-01-01T00%3A00%3A00Z&end_time=2025-01-31T23%3A59%3A59Z&environment=prod" \
>      -H "Authorization: Bearer <respanApiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

1 {
2   "count": 150,
3   "results": [
4     {
5       "id": "trace_abc123",
6       "trace_unique_id": "trace_abc123",
7       "root_span_unique_id": "span_root_123",
8       "organization_id": "org_xyz789",
9       "environment": "prod",
10       "customer_identifier": "user@example.com",
11       "start_time": "2024-01-15T10:30:00Z",
12       "end_time": "2024-01-15T10:30:02.500000Z",
13       "duration": 2.5,
14       "span_count": 5,
15       "llm_call_count": 2,
16       "total_cost": 0.00345,
17       "total_prompt_tokens": 150,
18       "total_completion_tokens": 75,
19       "total_tokens": 225,
20       "error_count": 0,
21       "name": "chat_completion",
22       "input": "[{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]",
23       "output": "{\"role\": \"assistant\", \"content\": \"Quantum computing is...\"}",
24       "metadata": {
25         "user_id": "user123"
26       },
27       "trace_group_identifier": "workflow_v1",
28       "session_identifier": "session456",
29       "model": "gpt-4"
30     }
31   ],
32   "next": "https://api.respan.ai/api/traces/list/?page=2",
33   "previous": null
34 }

Retrieve a paginated list of traces matching your filters. Supports the filter payload documented in the Filters API.

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, OpenAI or Azure OpenAI provider credentials go in Settings -> Providers or the request body credential_override field, not in this auth field.

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 null

URL for the next page of results.

previousstring or null

URL for the previous page of results.

Errors

400

Bad Request Error

401

Unauthorized Error

429

Too Many Requests Error

500

Internal Server Error