API ReferenceTraces

Retrieve a trace

Retrieve a single trace by trace_unique_id, including aggregate metrics and the full span tree. start_time and end_time are accepted query parameters for clients that keep trace lookups scoped to a known time window.

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, OpenAI or Azure OpenAI provider credentials go in Settings -> Providers or the request body credential_override field, not in this auth field.

Path parameters

trace_unique_idstringRequired
Unique trace identifier.

Query parameters

start_timedatetimeOptional

Optional start of the trace time window (ISO 8601). Use with end_time when you know the trace window.

end_timedatetimeOptional

Optional end of the trace time window (ISO 8601). Use with start_time when you know the trace window.

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