Skip to navigation
API ReferenceObservabilityTraces

Get a trace

Returns aggregate metrics and the full span tree. Metadata keys beginning with _ are reserved for platform use and omitted from span and trace read responses.

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.
inputstring or nullOptional

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

outputstring or nullOptional

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

403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error