Sign in
spans

Create a span

Create a request-log span via the logging API. This is the standard create endpoint; /api/request-logs/create/ remains supported as a legacy alias. For LLM request logs, send prompt_messages, completion_message, token counts, timing, metadata, tools, and trace fields directly in the body. generation_time is accepted and normalized to latency; ttft is accepted and normalized to time_to_first_token. The stored environment is derived from the API key environment, so use a key for the target environment rather than relying on a body override.

post/api/request-logs/

Headers

Authorizationstring required

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.

Request body

modelstring required

Model used for the span.

prompt_messagesApiRequestLogsPostRequestBodyContentApplicationJsonSchemaPromptMessagesItems[]

Chat input messages for the request log.

completion_messageApiRequestLogsPostRequestBodyContentApplicationJsonSchemaCompletionMessage

Assistant message returned by the model.

prompt_tokensinteger

Prompt/input tokens for the request. For Anthropic logs this corresponds to input_tokens before cache-token normalization.

completion_tokensinteger

Completion/output tokens for the request. For Anthropic logs this corresponds to output_tokens.

temperaturenumber double

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

top_pnumber double

Nucleus sampling parameter.

max_tokensinteger

Maximum tokens to generate.

generation_timenumber double

Accepted alias for total generation latency in seconds. Stored as latency in responses and query results.

ttftnumber double

Accepted alias for time to first token in seconds. Stored as time_to_first_token in responses and query results.

metadataApiRequestLogsPostRequestBodyContentApplicationJsonSchemaMetadata

Arbitrary key-value pairs for your reference.

environment'prod' | 'test'

Stored environment for the log. This is derived from the API key environment; body-supplied values do not override a prod/test key.

streamboolean

Whether the response was streamed.

status_codeinteger

HTTP status code of the request.

toolsApiRequestLogsPostRequestBodyContentApplicationJsonSchemaToolsItems[]

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

tool_callsApiRequestLogsPostRequestBodyContentApplicationJsonSchemaToolCallsItems[]

Tool calls returned by the model.

timestampstring date-time

ISO 8601 timestamp when the request completed.

trace_unique_idstring

Trace ID to link spans into a trace tree.

span_namestring

Name of this span within the workflow.

span_parent_idstring

Parent span ID. Builds the trace hierarchy.

span_workflow_namestring

Name of the parent workflow.

custom_identifierstring

Indexed custom identifier for fast querying.

thread_identifierstring

Conversation thread ID for multi-turn conversations.

group_identifierstring

Groups related spans together.

latencynumber double

Total request latency in seconds. generation_time is also accepted and normalizes to this field.

time_to_first_tokennumber double

Time to first token in seconds. ttft is also accepted and normalizes to this field.

log_type'chat' | 'completion' | 'response' | 'embedding' | 'speech' | 'transcription' | 'workflow' | 'agent' | 'task' | 'tool' | 'guardrail' | 'reranker' | 'other'

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

messagesApiRequestLogsPostRequestBodyContentApplicationJsonSchemaMessagesItems[]

Legacy chat input field. Equivalent to prompt_messages; prefer input for new integrations.

costnumber double

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

tokens_per_secondnumber double

Generation speed in tokens per second.

propertiesApiRequestLogsPostRequestBodyContentApplicationJsonSchema

Typed metadata that preserves native JSON types.

variablesApiRequestLogsPostRequestBodyContentApplicationJsonSchemaVariables

Variables used for prompt templates.

customer_identifierstring

Identifier for the end user who made this request.

response_formatApiRequestLogsPostRequestBodyContentApplicationJsonSchemaResponseFormat

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

frequency_penaltynumber double

Penalizes repeated tokens (-2 to 2).

presence_penaltynumber double

Penalizes tokens already present (-2 to 2).

error_messagestring

Error message if the request failed.

status'success' | 'error'

Request status.

prompt_idstring

ID of the Respan prompt template used.

prompt_namestring

Name of the prompt template.

is_custom_promptboolean

Set true when using a custom prompt_id.

start_timestring date-time

ISO 8601 timestamp when the request started.

full_requestApiRequestLogsPostRequestBodyContentApplicationJsonSchemaFullRequest

Full raw request object for reference.

full_responseApiRequestLogsPostRequestBodyContentApplicationJsonSchemaFullResponse

Full raw response object from the provider.

prompt_unit_pricenumber double

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

completion_unit_pricenumber double

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

respan_paramsApiRequestLogsPostRequestBodyContentApplicationJsonSchemaRespanParams

Preferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags.

keywordsai_paramsApiRequestLogsPostRequestBodyContentApplicationJsonSchemaKeywordsaiParams

Legacy alias for respan_params. Still accepted and merged into respan_params.

positive_feedbackboolean

User feedback. true = positive, false = negative.

Response

Span created successfully

idstring

Unique identifier for the span. Alias for unique_id.

unique_idstring

Full unique identifier for the created span.

organization_idstring

Organization identifier associated with the span.

customer_identifierstring

Customer identifier associated with the span.

status'success' | 'error'

Request status.

costnumber double

Computed or supplied request cost in USD.

timestampstring date-time

Timestamp when the span was recorded.

environmentstring

Environment derived from the API key used for the log.

latencynumber double

Stored total latency in seconds.

time_to_first_tokennumber double

Stored time to first token in seconds.

prompt_cache_creation_tokensinteger

Cache creation tokens normalized from usage.

prompt_cache_hit_tokensinteger

Cache read/hit tokens normalized from usage.

Changes