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

Alias of unique_organization_id.

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

Number of LLM-call spans.

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

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

outputstringOptional

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

metadataobjectOptional

Customer metadata. Keys beginning with _ are reserved and omitted from customer-facing responses.

trace_group_identifierstringOptional

Workflow or trace-group identifier.

session_identifierstringOptional
Session identifier when present.
modelstringOptional

Primary/root model used.

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