API ReferenceSpans

Retrieve a span

Retrieve a span by its unique ID. Returns the full span including input, output, metrics, metadata, trace context, evaluation scores, and credit/budget info (limit_info). 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

unique_idstringRequired
The unique ID of the log to get.

Response

Successful response for Retrieve span
idstring

Span ID (alias of unique_id).

unique_idstringOptional
Stored unique span ID.
span_unique_idstringOptional
Tracing span ID, when supplied.
trace_unique_idstringOptional
Parent trace ID.
span_namestringOptional
Span name.
span_parent_idstringOptional
Parent span ID.
span_workflow_namestringOptional
Workflow name associated with the span.
timestampdatetimeOptional
Completion timestamp.
start_timedatetimeOptional
Start timestamp.
period_startdatetimeOptional

Billing/aggregation period start.

period_enddatetimeOptional

Billing/aggregation period end.

inputstring or map from strings to any or list of any or double or booleanOptional
Canonical span input.
outputstring or map from strings to any or list of any or double or booleanOptional
Canonical span output.
prompt_messageslist of maps from strings to anyOptional
completion_messagemap from strings to anyOptional
completion_messageslist of anyOptional
full_requestmap from strings to anyOptional

Credential-sanitized full request.

full_responsemap from strings to anyOptional

Credential-sanitized full response.

modelstringOptional
Model used by the span.
provider_idstringOptional
Provider route used by the span.
environmentstringOptional

API-key environment.

log_typestringOptional

Span/log type.

log_methodstringOptional
How this span was ingested.
statusstringOptional
Span status.
status_codeintegerOptional
HTTP or application status code.
error_codestringOptional<=120 characters
Normalized error code.
error_messagestringOptional
Error message, when the span failed.
warningsstring or map from strings to any or list of any or double or booleanOptional
Warnings captured for the request.
prompt_tokensintegerOptional
Input token count.
completion_tokensintegerOptional
Output token count.
total_request_tokensintegerOptional
Total token count.
prompt_cache_hit_tokensintegerOptional

Cached input-token count.

prompt_cache_creation_tokensintegerOptional

Cache-creation input-token count.

reasoning_tokensintegerOptional

Reasoning-token count.

costdoubleOptional
Cost in USD.
latencydoubleOptional

End-to-end latency in seconds.

time_to_first_tokendoubleOptional
Time to first token in seconds.
tokens_per_seconddoubleOptional
Output throughput.
routing_timedoubleOptional
Gateway routing time.
metadatamap from strings to anyOptional

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

propertiesstring or map from strings to any or list of any or double or booleanOptional
Typed span properties.
variablesmap from strings to anyOptional
toolslist of maps from strings to anyOptional
tool_callslist of maps from strings to anyOptional
scoresmap from strings to objectsOptional
Evaluation scores keyed by evaluator identifier or slug.
customer_identifierstringOptional

End-customer identifier.

customer_emailstringOptional

End-customer email.

customer_namestringOptional

End-customer name.

custom_identifierstringOptional
Indexed custom identifier.
group_identifierstringOptional
Group identifier.
session_identifierstringOptional
Session identifier.
thread_identifierstringOptional
Conversation thread identifier.
organization_idstringOptional
Organization UUID.
unique_organization_idstringOptional
Organization UUID.
organization_key_idstringOptional

API-key identifier.

organization_key_namestringOptional

API-key display name.

prompt_idstringOptional
Prompt family ID.
prompt_namestringOptional
Prompt display name.
prompt_version_numberintegerOptional
Prompt version number.
deployment_idstringOptional
Deployment ID.
deployment_namestringOptional
Deployment name.
streambooleanOptional
Whether the response streamed.
temperaturedoubleOptional
Sampling temperature.
top_pdoubleOptional

Nucleus-sampling parameter.

max_tokensintegerOptional
Configured generation limit.
response_formatmap from strings to anyOptional
limit_infoobjectOptional
blurredbooleanOptional

When true, usage policy reduced the response to visibility-safe fields.

Errors

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