Create a span via the logging API. This is the standard create endpoint. `/api/request-logs/create/` remains supported as a legacy alias. Prefer universal `input` and `output` fields; legacy chat fields like `messages`, `prompt_messages`, and `completion_message` are still accepted for backward compatibility. Respan-specific controls can be sent at the top level or nested under `respan_params`.
Headers
AuthorizationstringRequired
Bearer token. Use Bearer YOUR_API_KEY.
Request
This endpoint expects an object.
modelstringRequired
Model used for the span.
log_typeenumOptionalDefaults to chat
Type of span. Determines how input and output are parsed.
inputstring or map from strings to any or list of objectsOptional
Preferred universal input field. For chat spans, send an array of message objects or a JSON string. For non-chat spans, send any string/object/array structure that represents the span input.
outputstring or map from strings to any or list of objectsOptional
Preferred universal output field. For chat spans, send an assistant message object or a JSON string. For non-chat spans, send any string/object/array structure that represents the span output.
messageslist of objectsOptional
Legacy chat input field. Equivalent to prompt_messages; prefer input for new integrations.
prompt_messageslist of objectsOptional
Legacy chat input field. Prefer input for new integrations.
completion_messageobjectOptional
Legacy chat output field. Prefer output for new integrations.
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.
propertiesobjectOptional
Typed metadata that preserves native JSON types.
variablesobjectOptional
Variables used for prompt templates.
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 objectsOptional
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.
stopstring or list of stringsOptional
Stop sequence or 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:
streambooleanOptionalDefaults to false
Whether the response was streamed.
prompt_idstringOptional
ID of the Respan prompt template used.
prompt_namestringOptional
Name of the prompt template.
is_custom_promptbooleanOptionalDefaults to false
Set true when using a custom prompt_id.
timestampdatetimeOptional
ISO 8601 timestamp when the request completed.
start_timedatetimeOptional
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_paramsobjectOptional
Preferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags.
keywordsai_paramsobjectOptional
Legacy alias for respan_params. Still accepted and merged into respan_params.
positive_feedbackbooleanOptional
User feedback. true = positive, false = negative.
Response
Span created successfully
idstring
Unique identifier for the span. Alias for unique_id.
Create a span via the logging API. This is the standard create endpoint. /api/request-logs/create/ remains supported as a legacy alias. Prefer universal input and output fields; legacy chat fields like messages, prompt_messages, and completion_message are still accepted for backward compatibility. Respan-specific controls can be sent at the top level or nested under respan_params.
