For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DiscordPlatform
DocumentationIntegrationsAPI referenceSDKsChangelog
DocumentationIntegrationsAPI referenceSDKsChangelog
  • API Reference
      • POSTList traces
      • POSTBulk delete traces
      • GETRetrieve a trace
      • DELDelete a trace
      • PATCHShare a trace publicly
      • GETRetrieve a public trace
      • POSTIngest spans from traces (v1 legacy)
      • POSTCreate a trace (OTLP)
  • Reference
    • Filters API Reference
LogoLogo
DiscordPlatform
API ReferenceTraces

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=production" \
>     -H "Authorization: Bearer sk_live_xxxxx" \
>     -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": "production",
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.
Was this page helpful?
Previous

Bulk delete traces

Next
Built with

Headers

AuthorizationstringRequired

Bearer token. Use Bearer YOUR_API_KEY.

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.

operatorenumOptionalDefaults to AND
Logical operator for combining filters when supported by the client payload.
Allowed values:

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