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

Retrieve a trace

GET
https://api.respan.ai/api/traces/:trace_unique_id/
GET
/api/traces/:trace_unique_id/
$curl https://api.respan.ai/api/traces/trace_unique_id/ \
>     -H "Authorization: Bearer sk_live_xxxxx"
1{
2  "id": "trace_abc123",
3  "trace_unique_id": "trace_abc123",
4  "root_span_unique_id": "span_root_123",
5  "unique_organization_id": "org_xyz789",
6  "organization_id": "org_xyz789",
7  "organization_name": "Acme Inc",
8  "environment": "production",
9  "customer_identifier": "user@example.com",
10  "start_time": "2024-01-15T10:30:00Z",
11  "end_time": "2024-01-15T10:30:02.500000Z",
12  "duration": 2.5,
13  "span_count": 3,
14  "llm_call_count": 2,
15  "total_cost": 0.00345,
16  "total_prompt_tokens": 150,
17  "total_completion_tokens": 75,
18  "total_tokens": 225,
19  "error_count": 0,
20  "name": "chat_completion",
21  "input": "[{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]",
22  "output": "{\"role\": \"assistant\", \"content\": \"Quantum computing is a revolutionary technology...\"}",
23  "metadata": {
24    "user_id": "user123"
25  },
26  "trace_group_identifier": "workflow_v1",
27  "session_identifier": "session456",
28  "model": "gpt-4",
29  "span_tree": [
30    {
31      "id": "log_root_1",
32      "unique_id": "log_root_1",
33      "span_unique_id": "span_root_123",
34      "span_name": "chat_completion",
35      "span_parent_id": null,
36      "trace_unique_id": "trace_abc123",
37      "log_type": "chat",
38      "timestamp": "2024-01-15T10:30:02Z",
39      "start_time": "2024-01-15T10:30:00Z",
40      "prompt_tokens": 50,
41      "completion_tokens": 75,
42      "cost": 0.00345,
43      "model": "gpt-4",
44      "latency": 2,
45      "status_code": 200,
46      "status": "success",
47      "input": "[{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]",
48      "output": "{\"role\": \"assistant\", \"content\": \"Quantum computing is a revolutionary technology...\"}",
49      "children": []
50    }
51  ]
52}

Retrieve a single trace by trace_unique_id, including aggregate metrics and the full span tree.

Was this page helpful?
Previous

Delete a trace

Next
Built with

Path parameters

trace_unique_idstringRequired
Unique trace identifier.

Headers

AuthorizationstringRequired

Bearer token. Use Bearer YOUR_API_KEY.

Response

Trace detail with span tree.
idstring
Trace identifier.
trace_unique_idstring
Unique trace identifier.
root_span_unique_idstring
Root span ID for the trace.
unique_organization_idstring
Organization unique ID.
organization_idstring

Alias of unique_organization_id.

organization_namestring
Organization name when available.
organization_key_idstring
API key identifier used to create the trace.
environmentstring
Environment for the trace.
customer_identifierstring
Customer or user identifier.
start_timedatetime
When the trace started.
end_timedatetime
When the trace ended.
durationdouble
Total duration in seconds.
span_countinteger
Total spans in the trace.
llm_call_countinteger

Number of LLM-call spans.

total_costdouble
Total cost in USD.
total_prompt_tokensinteger
Sum of prompt tokens.
total_completion_tokensinteger
Sum of completion tokens.
total_tokensinteger
Sum of all tokens.
error_countinteger
Number of error spans.
namestring
Root span name.
inputstring

Root span input. API key responses may include full storage-enriched content.

outputstring

Root span output. API key responses may include full storage-enriched content.

metadataobject
Trace metadata.
trace_group_identifierstring

Workflow or trace-group identifier.

session_identifierstring
Session identifier when present.
modelstring

Primary/root model used.

storage_object_keystring
Storage object key for the root span payload when present.
span_treelist of objects
Hierarchical span tree for the trace.

Errors

401
Unauthorized Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error