API ReferenceTraces

Retrieve a trace

Retrieve a single trace by trace_unique_id, including aggregate metrics and the full span tree. 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.

Path parameters

trace_unique_idstringRequired
Unique trace identifier.

Response

Trace detail with span tree.
idstringOptional
Trace identifier.
trace_unique_idstringOptional
Unique trace identifier.
root_span_unique_idstringOptional
Root span ID for the trace.
unique_organization_idstringOptional
Organization unique ID.
organization_idstringOptional
Failed to render this content

An error occurred while compiling this section of the page.

Serialize MDX timed out
organization_namestringOptional
Organization name when available.
organization_key_idstringOptional
API key identifier used to create the trace.
environmentstringOptional
Environment for the trace.
customer_identifierstringOptional
Customer or user identifier.
start_timedatetimeOptional
When the trace started.
end_timedatetimeOptional
When the trace ended.
durationdoubleOptional
Total duration in seconds.
span_countintegerOptional
Total spans in the trace.
llm_call_countintegerOptional
Failed to render this content

An error occurred while compiling this section of the page.

Serialize MDX timed out
total_costdoubleOptional
Total cost in USD.
total_prompt_tokensintegerOptional
Sum of prompt tokens.
total_completion_tokensintegerOptional
Sum of completion tokens.
total_tokensintegerOptional
Sum of all tokens.
error_countintegerOptional
Number of error spans.
namestringOptional
Root span name.
inputstringOptional
Failed to render this content

An error occurred while compiling this section of the page.

Serialize MDX timed out
outputstringOptional
Failed to render this content

An error occurred while compiling this section of the page.

Serialize MDX timed out
metadataobjectOptional
Failed to render this content

An error occurred while compiling this section of the page.

Serialize MDX timed out
trace_group_identifierstringOptional
Failed to render this content

An error occurred while compiling this section of the page.

Serialize MDX timed out
session_identifierstringOptional
Session identifier when present.
modelstringOptional
Failed to render this content

An error occurred while compiling this section of the page.

Serialize MDX timed out
storage_object_keystringOptional
Storage object key for the root span payload when present.
span_treelist of objectsOptional
Hierarchical span tree for the trace.

Errors

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