API ReferenceObserveSpans

Create a span

Create a span representing a single LLM interaction. Spans are the core data unit in Respan — every LLM call, agent step, or tool invocation is stored as a span.

Span size limit: 20MB per payload.

Headers

AuthorizationstringRequired

Bearer token. Use Bearer YOUR_API_KEY.

Request

This endpoint expects an object.
prompt_messageslist of stringsOptional

Deprecated. Use input instead.

completion_messageobjectOptional

Deprecated. Use output instead.

inputstring or map from strings to any or list of stringsOptional

The input to the model. Format depends on log_type.

outputstring or map from strings to any or list of stringsOptional

The output from the model. Format depends on log_type.

log_typeenumOptionalDefaults to chat

Type of span. Determines how input and output are parsed.

modelstringOptional
Model used for the request.
usageobjectOptional
Token usage for the request.
costdoubleOptional

Cost in USD. Auto-calculated from model pricing if omitted.

latencydoubleOptional
Total request latency in seconds.
time_to_first_tokendoubleOptional
Time to first token in seconds.
tokens_per_seconddoubleOptional
Generation speed in tokens per second.
metadataobjectOptional

Arbitrary key-value pairs for your reference.

customer_identifierstringOptional<=254 characters
Identifier for the end user who made this request.
customer_paramsobjectOptional
Extended customer information.
thread_identifierstringOptional

Conversation thread ID for multi-turn conversations.

custom_identifierstringOptional
Indexed custom identifier for fast querying.
group_identifierstringOptional
Groups related spans together.
trace_unique_idstringOptional
Trace ID to link spans into a trace tree.
span_workflow_namestringOptional
Name of the parent workflow.
span_namestringOptional
Name of this span within the workflow.
span_parent_idstringOptional
Parent span ID. Builds the trace hierarchy.
toolslist of stringsOptional

Tools available to the model (OpenAI function calling format).

tool_choicestring or map from strings to anyOptional

Controls tool selection. "none", "auto", or a specific tool object.

response_formatobjectOptional

Response format configuration (e.g. JSON mode or structured output).

temperaturedoubleOptionalDefaults to 1

Sampling temperature (0-2). Higher = more random.

top_pdoubleOptionalDefaults to 1
Nucleus sampling parameter.
frequency_penaltydoubleOptional

Penalizes repeated tokens (-2 to 2).

presence_penaltydoubleOptional

Penalizes tokens already present (-2 to 2).

max_tokensintegerOptional
Maximum tokens to generate.
stoplist of stringsOptional
Stop sequences where generation halts.
status_codeintegerOptionalDefaults to 200
HTTP status code of the request.
error_messagestringOptional
Error message if the request failed.
warningsstring or map from strings to anyOptional
Warnings from the request.
statusenumOptional
Request status.
Allowed values:
streambooleanOptional
Whether the response was streamed.
prompt_idstringOptional
ID of the Respan prompt template used.
prompt_namestringOptional
Name of the prompt template.
is_custom_promptbooleanOptional

Set true when using a custom prompt_id.

timestampstringOptional
ISO 8601 timestamp when the request completed.
start_timestringOptional
ISO 8601 timestamp when the request started.
full_requestobjectOptional
Full raw request object for reference.
full_responseobjectOptional
Full raw response object from the provider.
prompt_unit_pricedoubleOptional

Custom price per 1M prompt tokens (for self-hosted/fine-tuned models).

completion_unit_pricedoubleOptional

Custom price per 1M completion tokens (for self-hosted/fine-tuned models).

respan_api_controlsobjectOptional
Controls for the Respan logging API behavior.
positive_feedbackbooleanOptional

User feedback. true = positive, false = negative.

Response

Successful response for Create span
usageobject

Errors

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