Create a span
POST
https://api.respan.ai/api/request-logs/Records a span through the logging API. /api/request-logs/create/ remains supported as a legacy alias. generation_time is normalized to latency, and ttft to time_to_first_token. The API key determines the stored environment; a body value does not override it. Metadata keys beginning with _ are reserved for platform use and omitted from span and trace read responses.
Servers
https://api.respan.ai — Respan API Server
Authentication
RespanApiKey
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.
HTTP scheme: bearer; format: Respan API key.
Authorization: Bearer $RESPAN_API_KEYRequest body
A request body is required.
application/json
Field Type Requirement Description and constraints
$ object Required body
Reference:
#/components/schemas/SpanCreateRequestmodel string Required in parentModel used for the span.
Example:
Example:
"gpt-4o-mini"prompt_messages array<object> Optional
Chat input messages for the request log.
Example:
Example:
[{"role":"user","content":"Hello"}]prompt_messages[] object Array item—
completion_message object OptionalAssistant message returned by the model.
Example:
Example:
{"role":"assistant","content":"Hi there!"}prompt_tokens integer OptionalPrompt/input tokens for the request. For Anthropic logs this corresponds to
Example:
input_tokens before cache-token normalization.Example:
50completion_tokens integer OptionalCompletion/output tokens for the request. For Anthropic logs this corresponds to
Example:
output_tokens.Example:
100usage object Optional
Provider usage object. Cache token fields such as
Example:
cache_creation_input_tokens and cache_read_input_tokens are accepted and normalized into Respan cache-token counters.Example:
{"cache_creation_input_tokens":0,"cache_read_input_tokens":0}usage.prompt_tokens integer Optional—
usage.completion_tokens integer Optional—
usage.total_tokens integer Optional—
usage.input_tokens integer OptionalAnthropic input token count.
usage.output_tokens integer OptionalAnthropic output token count.
usage.cache_creation_input_tokens integer OptionalAnthropic cache-creation input tokens. Normalized to
prompt_cache_creation_tokens.usage.cache_read_input_tokens integer OptionalAnthropic cache-read input tokens. Normalized to
prompt_cache_hit_tokens.temperature number OptionalSampling temperature (0-2). Higher = more random.
Default:
Example:
Default:
1Example:
0.7top_p number OptionalNucleus sampling parameter.
Default:
Example:
Default:
1Example:
1max_tokens integer OptionalMaximum tokens to generate.
Example:
Example:
1024generation_time number OptionalAccepted alias for total generation latency in seconds. Stored as
Example:
latency in responses and query results.Example:
1.23ttft number OptionalAccepted alias for time to first token in seconds. Stored as
Example:
time_to_first_token in responses and query results.Example:
0.35customer_params object Optional
Extended customer information.
Example:
customer_identifier inside this object is promoted to the log customer identifier.Example:
{"customer_identifier":"user_123","email":"alice@example.com","name":"Alice"}customer_params.customer_identifier string Optional—
customer_params.email string Optional—
customer_params.name string Optional—
metadata object OptionalArbitrary customer metadata. Keys beginning with
Example:
_ are reserved and omitted from customer-facing read responses.Example:
{"env":"production","feature":"chat"}environment string OptionalStored environment for the log. This is derived from the API key environment; body-supplied values do not override a prod/test key.
Allowed:
Read only
Example:
Allowed:
"prod", "test"Read only
Example:
"prod"stream boolean OptionalWhether the response was streamed.
Default:
Example:
Default:
falseExample:
falsestatus_code integer OptionalHTTP status code of the request.
Default:
Example:
Default:
200Example:
200tools array<object> Optional
Tools available to the model (OpenAI function calling format).
Example:
Example:
[{"type":"function","function":{"name":"lookup_order","description":"Lookup an order by ID"}}]tools[] object Array item—
tool_calls array<object> Optional
Tool calls returned by the model.
Example:
Example:
[{"id":"call_abc123","type":"function","function":{"name":"lookup_order","arguments":"{\"order_id\":\"ord_123\"}"}}]tool_calls[] object Array item—
timestamp string OptionalISO 8601 timestamp when the request completed.
Format:
Example:
Format:
date-timeExample:
"2025-03-15T10:30:00Z"trace_unique_id string OptionalTrace ID to link spans into a trace tree.
Example:
Example:
"trace_abc123"span_name string OptionalName of this span within the workflow.
Example:
Example:
"classify_intent"span_parent_id string OptionalParent span ID. Builds the trace hierarchy.
Example:
Example:
"span_parent_001"span_workflow_name string OptionalName of the parent workflow.
Example:
Example:
"customer_support_flow"custom_identifier string OptionalIndexed custom identifier for fast querying.
Example:
Example:
"order_456"thread_identifier string OptionalConversation thread ID for multi-turn conversations.
Example:
Example:
"thread_abc"group_identifier string OptionalGroups related spans together.
Example:
Example:
"batch_789"latency number OptionalTotal request latency in seconds.
Example:
generation_time is also accepted and normalizes to this field.Example:
1.23time_to_first_token number OptionalTime to first token in seconds.
Example:
ttft is also accepted and normalizes to this field.Example:
0.35log_type string OptionalType of span. Determines how
Allowed:
Default:
Example:
input and output are parsed.Allowed:
"chat", "completion", "response", "embedding", "speech", "transcription", "workflow", "agent", "task", "tool", "guardrail", "reranker", "other"Default:
chatExample:
"chat"input string or object or array<object> Optional
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.
Example:
Example:
"[{\"role\": \"user\", \"content\": \"Hello\"}]"input (oneOf 1) string Schema variant—
input (oneOf 2) object Schema variant—
input (oneOf 3) array<object> Schema variant
—
input (oneOf 3)[] object Array item—
output string or object or array<object> Optional
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.
Example:
Example:
"{\"role\": \"assistant\", \"content\": \"Hi there!\"}"output (oneOf 1) string Schema variant—
output (oneOf 2) object Schema variant—
output (oneOf 3) array<object> Schema variant
—
output (oneOf 3)[] object Array item—
messages array<object> Optional
Legacy chat input field. Equivalent to
Example:
prompt_messages; prefer input for new integrations.Example:
[{"role":"user","content":"Hello"}]messages[] object Array item—
cost number OptionalCost in USD. Auto-calculated from model pricing if omitted.
Example:
Example:
0.0025tokens_per_second number OptionalGeneration speed in tokens per second.
Example:
Example:
45.2properties object OptionalTyped metadata that preserves native JSON types.
Example:
Example:
{"cache_hit":false,"score":0.98}variables object OptionalVariables used for prompt templates.
Example:
Example:
{"customer_name":"Alice"}customer_identifier string OptionalIdentifier for the end user who made this request.
Maximum length:
Example:
Maximum length:
254Example:
"user_123"tool_choice string or object Optional
Controls tool selection.
"none", "auto", or a specific tool object.tool_choice (oneOf 1) string Schema variant—
tool_choice (oneOf 2) object Schema variant—
response_format object OptionalResponse format configuration (e.g. JSON mode or structured output).
frequency_penalty number OptionalPenalizes repeated tokens (-2 to 2).
Example:
Example:
0presence_penalty number OptionalPenalizes tokens already present (-2 to 2).
Example:
Example:
0stop string or array<string> Optional
Stop sequence or sequences where generation halts.
stop (oneOf 1) string Schema variant—
stop (oneOf 2) array<string> Schema variant
—
stop (oneOf 2)[] string Array item—
error_message string OptionalError message if the request failed.
Example:
Example:
""warnings string or object Optional
Warnings from the request.
warnings (oneOf 1) string Schema variant—
warnings (oneOf 2) object Schema variant—
status string OptionalRequest status.
Allowed:
Example:
error is stored as failed.Allowed:
"success", "error"Example:
"success"prompt_id string OptionalID of the Respan prompt template used.
Example:
Example:
"prompt_abc123"prompt_name string OptionalName of the prompt template.
Example:
Example:
"customer_support"is_custom_prompt boolean OptionalNot read at the top level. Respan reads
Default:
Example:
is_custom_prompt only inside a prompt object, as in {"prompt": {"prompt_id": "your-id", "is_custom_prompt": true}}. Set it there for a prompt you manage outside Respan. Otherwise Respan looks up prompt.prompt_id among your saved prompts and rejects the span if none matches. A top-level prompt_id is logged as sent and isn’t looked up.Default:
falseExample:
falsestart_time string OptionalISO 8601 timestamp when the request started.
Format:
Example:
Format:
date-timeExample:
"2025-03-15T10:29:59Z"full_request object OptionalFull raw request object for reference.
full_response object OptionalFull raw response object from the provider.
prompt_unit_price number OptionalCustom price per 1M prompt tokens (for self-hosted/fine-tuned models).
Example:
Example:
2.5completion_unit_price number OptionalCustom price per 1M completion tokens (for self-hosted/fine-tuned models).
Example:
Example:
10respan_params object OptionalPreferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags.
keywordsai_params object OptionalLegacy alias for
respan_params. Still accepted and merged into respan_params.positive_feedback boolean OptionalUser feedback.
Example:
true = positive, false = negative.Example:
trueerror_code string OptionalNormalized application or provider error code.
Maximum length:
Maximum length:
120OpenAPI request schema
{
"$ref": "#/components/schemas/SpanCreateRequest"
}Example
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "Hello"
}
],
"completion_message": {
"role": "assistant",
"content": "Hi there!"
},
"prompt_tokens": 50,
"completion_tokens": 100,
"usage": {
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
},
"temperature": 0.7,
"top_p": 1,
"max_tokens": 1024,
"generation_time": 1.23,
"ttft": 0.35,
"customer_params": {
"customer_identifier": "user_123",
"email": "alice@example.com",
"name": "Alice"
},
"metadata": {
"feature": "chat"
},
"stream": false,
"status_code": 200,
"tools": [
{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Lookup an order by ID"
}
}
],
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "lookup_order",
"arguments": "{\"order_id\":\"ord_123\"}"
}
}
],
"timestamp": "2026-06-04T10:30:00Z"
}Responses
201
The stored span, with the same fields as Get a span.
application/json
Field Type Requirement Description and constraints
$ object Body
—
id string OptionalUnique identifier for the span. Alias for
unique_id.unique_id string OptionalFull unique identifier for the created span.
organization_id string OptionalOrganization identifier associated with the span.
customer_identifier string OptionalCustomer identifier associated with the span.
status string OptionalStored status.
Allowed:
warning means the span was stored with warnings, for example estimated token usage.Allowed:
"success", "warning", "failed", "pending", "running"cost number OptionalComputed or supplied request cost in USD.
timestamp string OptionalTimestamp when the span was recorded.
Format:
Format:
date-timeenvironment string OptionalEnvironment derived from the API key used for the log.
latency number OptionalStored total latency in seconds.
time_to_first_token number OptionalStored time to first token in seconds.
prompt_cache_creation_tokens integer OptionalCache creation tokens normalized from usage.
prompt_cache_hit_tokens integer OptionalCache read/hit tokens normalized from usage.
OpenAPI response schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the span. Alias for `unique_id`."
},
"unique_id": {
"type": "string",
"description": "Full unique identifier for the created span."
},
"organization_id": {
"type": "string",
"description": "Organization identifier associated with the span."
},
"customer_identifier": {
"type": "string",
"description": "Customer identifier associated with the span."
},
"status": {
"type": "string",
"description": "Stored status. `warning` means the span was stored with warnings, for example estimated token usage.",
"enum": [
"success",
"warning",
"failed",
"pending",
"running"
]
},
"cost": {
"type": "number",
"description": "Computed or supplied request cost in USD."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the span was recorded."
},
"environment": {
"type": "string",
"description": "Environment derived from the API key used for the log."
},
"latency": {
"type": "number",
"description": "Stored total latency in seconds."
},
"time_to_first_token": {
"type": "number",
"description": "Stored time to first token in seconds."
},
"prompt_cache_creation_tokens": {
"type": "integer",
"description": "Cache creation tokens normalized from usage."
},
"prompt_cache_hit_tokens": {
"type": "integer",
"description": "Cache read/hit tokens normalized from usage."
}
}
}Example
{
"id": "log_abc123...",
"unique_id": "log_abc123...",
"organization_id": "org_xyz789",
"customer_identifier": "user_123",
"status": "success",
"cost": 0.000375,
"timestamp": "2026-03-25T10:30:00Z",
"environment": "prod",
"latency": 1.23,
"time_to_first_token": 0.35,
"prompt_cache_creation_tokens": 0,
"prompt_cache_hit_tokens": 0
}400
Bad Request
application/json
Field Type Requirement Description and constraints
$ object Body
—
id string OptionalError identifier when available.
error string OptionalError message.
error_class string OptionalError classification.
OpenAPI response schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Error identifier when available."
},
"error": {
"type": "string",
"description": "Error message."
},
"error_class": {
"type": "string",
"description": "Error classification."
}
}
}Example
{
"id": "request_log_organization_banned",
"error": "Your organization has been banned from creating logs.",
"error_class": "AuthenticationError"
}403
The API key is missing, invalid or expired.
application/json
Field Type Requirement Description and constraints
$ object Body
—
detail string Required in parent—
OpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}422
Unprocessable Entity
application/json
Field Type Requirement Description and constraints
$ object Body
—
error string OptionalValidation error message.
Example:
Example:
"Invalid logging format: [{'type': 'missing', 'loc': ['model'], 'msg': 'Field required'}]"OpenAPI response schema
{
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Validation error message.",
"example": "Invalid logging format: [{'type': 'missing', 'loc': ['model'], 'msg': 'Field required'}]"
}
}
}429
Rate Limited
application/json
Field Type Requirement Description and constraints
$ object Body
—
detail string OptionalRate limit detail.
Example:
Example:
"Rate limit exceeded. Please try again later."error string OptionalError message.
Example:
Example:
"Too many log creation requests. Please slow down."OpenAPI response schema
{
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "Rate limit detail.",
"example": "Rate limit exceeded. Please try again later."
},
"error": {
"type": "string",
"description": "Error message.",
"example": "Too many log creation requests. Please slow down."
}
}
}500
Internal Server Error
application/json
Field Type Requirement Description and constraints
$ object Body
—
error string OptionalError message
Example:
Example:
"Internal server error"OpenAPI response schema
{
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error message",
"example": "Internal server error"
}
}
}OpenAPI source
The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.
OpenAPI operation
{
"summary": "Create a span",
"operationId": "createSpan",
"tags": [
"Spans"
],
"description": "Records a span through the logging API. `/api/request-logs/create/` remains supported as a legacy alias. `generation_time` is normalized to `latency`, and `ttft` to `time_to_first_token`. The API key determines the stored `environment`; a body value does not override it. Metadata keys beginning with `_` are reserved for platform use and omitted from span and trace read responses.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SpanCreateRequest"
},
"example": {
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "Hello"
}
],
"completion_message": {
"role": "assistant",
"content": "Hi there!"
},
"prompt_tokens": 50,
"completion_tokens": 100,
"usage": {
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
},
"temperature": 0.7,
"top_p": 1,
"max_tokens": 1024,
"generation_time": 1.23,
"ttft": 0.35,
"customer_params": {
"customer_identifier": "user_123",
"email": "alice@example.com",
"name": "Alice"
},
"metadata": {
"feature": "chat"
},
"stream": false,
"status_code": 200,
"tools": [
{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Lookup an order by ID"
}
}
],
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "lookup_order",
"arguments": "{\"order_id\":\"ord_123\"}"
}
}
],
"timestamp": "2026-06-04T10:30:00Z"
}
}
}
},
"responses": {
"201": {
"description": "The stored span, with the same fields as Get a span.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the span. Alias for `unique_id`."
},
"unique_id": {
"type": "string",
"description": "Full unique identifier for the created span."
},
"organization_id": {
"type": "string",
"description": "Organization identifier associated with the span."
},
"customer_identifier": {
"type": "string",
"description": "Customer identifier associated with the span."
},
"status": {
"type": "string",
"description": "Stored status. `warning` means the span was stored with warnings, for example estimated token usage.",
"enum": [
"success",
"warning",
"failed",
"pending",
"running"
]
},
"cost": {
"type": "number",
"description": "Computed or supplied request cost in USD."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the span was recorded."
},
"environment": {
"type": "string",
"description": "Environment derived from the API key used for the log."
},
"latency": {
"type": "number",
"description": "Stored total latency in seconds."
},
"time_to_first_token": {
"type": "number",
"description": "Stored time to first token in seconds."
},
"prompt_cache_creation_tokens": {
"type": "integer",
"description": "Cache creation tokens normalized from usage."
},
"prompt_cache_hit_tokens": {
"type": "integer",
"description": "Cache read/hit tokens normalized from usage."
}
}
},
"example": {
"id": "log_abc123...",
"unique_id": "log_abc123...",
"organization_id": "org_xyz789",
"customer_identifier": "user_123",
"status": "success",
"cost": 0.000375,
"timestamp": "2026-03-25T10:30:00Z",
"environment": "prod",
"latency": 1.23,
"time_to_first_token": 0.35,
"prompt_cache_creation_tokens": 0,
"prompt_cache_hit_tokens": 0
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Error identifier when available."
},
"error": {
"type": "string",
"description": "Error message."
},
"error_class": {
"type": "string",
"description": "Error classification."
}
}
},
"example": {
"id": "request_log_organization_banned",
"error": "Your organization has been banned from creating logs.",
"error_class": "AuthenticationError"
}
}
}
},
"403": {
"$ref": "#/components/responses/InvalidApiKey"
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Validation error message.",
"example": "Invalid logging format: [{'type': 'missing', 'loc': ['model'], 'msg': 'Field required'}]"
}
}
}
}
}
},
"429": {
"description": "Rate Limited",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "Rate limit detail.",
"example": "Rate limit exceeded. Please try again later."
},
"error": {
"type": "string",
"description": "Error message.",
"example": "Too many log creation requests. Please slow down."
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error message",
"example": "Internal server error"
}
}
}
}
}
}
},
"security": [
{
"RespanApiKey": []
}
]
}OpenAPI path metadata
{}Referenced OpenAPI components
{
"responses": {
"InvalidApiKey": {
"description": "The API key is missing, invalid or expired.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
}
}
}
},
"schemas": {
"SpanCreateRequest": {
"type": "object",
"properties": {
"model": {
"type": "string",
"description": "Model used for the span.",
"example": "gpt-4o-mini"
},
"prompt_messages": {
"type": "array",
"items": {
"type": "object"
},
"description": "Chat input messages for the request log.",
"example": [
{
"role": "user",
"content": "Hello"
}
]
},
"completion_message": {
"type": "object",
"description": "Assistant message returned by the model.",
"example": {
"role": "assistant",
"content": "Hi there!"
}
},
"prompt_tokens": {
"type": "integer",
"description": "Prompt/input tokens for the request. For Anthropic logs this corresponds to `input_tokens` before cache-token normalization.",
"example": 50
},
"completion_tokens": {
"type": "integer",
"description": "Completion/output tokens for the request. For Anthropic logs this corresponds to `output_tokens`.",
"example": 100
},
"usage": {
"type": "object",
"description": "Provider usage object. Cache token fields such as `cache_creation_input_tokens` and `cache_read_input_tokens` are accepted and normalized into Respan cache-token counters.",
"properties": {
"prompt_tokens": {
"type": "integer"
},
"completion_tokens": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"input_tokens": {
"type": "integer",
"description": "Anthropic input token count."
},
"output_tokens": {
"type": "integer",
"description": "Anthropic output token count."
},
"cache_creation_input_tokens": {
"type": "integer",
"description": "Anthropic cache-creation input tokens. Normalized to `prompt_cache_creation_tokens`."
},
"cache_read_input_tokens": {
"type": "integer",
"description": "Anthropic cache-read input tokens. Normalized to `prompt_cache_hit_tokens`."
}
},
"example": {
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
},
"temperature": {
"type": "number",
"description": "Sampling temperature (0-2). Higher = more random.",
"default": 1,
"example": 0.7
},
"top_p": {
"type": "number",
"description": "Nucleus sampling parameter.",
"default": 1,
"example": 1
},
"max_tokens": {
"type": "integer",
"description": "Maximum tokens to generate.",
"example": 1024
},
"generation_time": {
"type": "number",
"description": "Accepted alias for total generation latency in seconds. Stored as `latency` in responses and query results.",
"example": 1.23
},
"ttft": {
"type": "number",
"description": "Accepted alias for time to first token in seconds. Stored as `time_to_first_token` in responses and query results.",
"example": 0.35
},
"customer_params": {
"type": "object",
"description": "Extended customer information. `customer_identifier` inside this object is promoted to the log customer identifier.",
"properties": {
"customer_identifier": {
"type": "string"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
}
},
"example": {
"customer_identifier": "user_123",
"email": "alice@example.com",
"name": "Alice"
}
},
"metadata": {
"type": "object",
"description": "Arbitrary customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing read responses.",
"example": {
"env": "production",
"feature": "chat"
}
},
"environment": {
"type": "string",
"description": "Stored environment for the log. This is derived from the API key environment; body-supplied values do not override a prod/test key.",
"enum": [
"prod",
"test"
],
"readOnly": true,
"example": "prod"
},
"stream": {
"type": "boolean",
"description": "Whether the response was streamed.",
"default": false,
"example": false
},
"status_code": {
"type": "integer",
"description": "HTTP status code of the request.",
"default": 200,
"example": 200
},
"tools": {
"type": "array",
"items": {
"type": "object"
},
"description": "Tools available to the model (OpenAI function calling format).",
"example": [
{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Lookup an order by ID"
}
}
]
},
"tool_calls": {
"type": "array",
"items": {
"type": "object"
},
"description": "Tool calls returned by the model.",
"example": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "lookup_order",
"arguments": "{\"order_id\":\"ord_123\"}"
}
}
]
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the request completed.",
"example": "2025-03-15T10:30:00Z"
},
"trace_unique_id": {
"type": "string",
"description": "Trace ID to link spans into a trace tree.",
"example": "trace_abc123"
},
"span_name": {
"type": "string",
"description": "Name of this span within the workflow.",
"example": "classify_intent"
},
"span_parent_id": {
"type": "string",
"description": "Parent span ID. Builds the trace hierarchy.",
"example": "span_parent_001"
},
"span_workflow_name": {
"type": "string",
"description": "Name of the parent workflow.",
"example": "customer_support_flow"
},
"custom_identifier": {
"type": "string",
"description": "Indexed custom identifier for fast querying.",
"example": "order_456"
},
"thread_identifier": {
"type": "string",
"description": "Conversation thread ID for multi-turn conversations.",
"example": "thread_abc"
},
"group_identifier": {
"type": "string",
"description": "Groups related spans together.",
"example": "batch_789"
},
"latency": {
"type": "number",
"description": "Total request latency in seconds. `generation_time` is also accepted and normalizes to this field.",
"example": 1.23
},
"time_to_first_token": {
"type": "number",
"description": "Time to first token in seconds. `ttft` is also accepted and normalizes to this field.",
"example": 0.35
},
"log_type": {
"type": "string",
"description": "Type of span. Determines how `input` and `output` are parsed.",
"default": "chat",
"enum": [
"chat",
"completion",
"response",
"embedding",
"speech",
"transcription",
"workflow",
"agent",
"task",
"tool",
"guardrail",
"reranker",
"other"
],
"example": "chat"
},
"input": {
"oneOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "object"
}
}
],
"description": "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.",
"example": "[{\"role\": \"user\", \"content\": \"Hello\"}]"
},
"output": {
"oneOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {
"type": "object"
}
}
],
"description": "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.",
"example": "{\"role\": \"assistant\", \"content\": \"Hi there!\"}"
},
"messages": {
"type": "array",
"items": {
"type": "object"
},
"description": "Legacy chat input field. Equivalent to `prompt_messages`; prefer `input` for new integrations.",
"example": [
{
"role": "user",
"content": "Hello"
}
]
},
"cost": {
"type": "number",
"description": "Cost in USD. Auto-calculated from model pricing if omitted.",
"example": 0.0025
},
"tokens_per_second": {
"type": "number",
"description": "Generation speed in tokens per second.",
"example": 45.2
},
"properties": {
"type": "object",
"description": "Typed metadata that preserves native JSON types.",
"example": {
"cache_hit": false,
"score": 0.98
}
},
"variables": {
"type": "object",
"description": "Variables used for prompt templates.",
"example": {
"customer_name": "Alice"
}
},
"customer_identifier": {
"type": "string",
"description": "Identifier for the end user who made this request.",
"maxLength": 254,
"example": "user_123"
},
"tool_choice": {
"oneOf": [
{
"type": "string"
},
{
"type": "object"
}
],
"description": "Controls tool selection. `\"none\"`, `\"auto\"`, or a specific tool object."
},
"response_format": {
"type": "object",
"description": "Response format configuration (e.g. JSON mode or structured output)."
},
"frequency_penalty": {
"type": "number",
"description": "Penalizes repeated tokens (-2 to 2).",
"example": 0
},
"presence_penalty": {
"type": "number",
"description": "Penalizes tokens already present (-2 to 2).",
"example": 0
},
"stop": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Stop sequence or sequences where generation halts."
},
"error_message": {
"type": "string",
"description": "Error message if the request failed.",
"example": ""
},
"warnings": {
"oneOf": [
{
"type": "string"
},
{
"type": "object"
}
],
"description": "Warnings from the request."
},
"status": {
"type": "string",
"description": "Request status. `error` is stored as `failed`.",
"enum": [
"success",
"error"
],
"example": "success"
},
"prompt_id": {
"type": "string",
"description": "ID of the Respan prompt template used.",
"example": "prompt_abc123"
},
"prompt_name": {
"type": "string",
"description": "Name of the prompt template.",
"example": "customer_support"
},
"is_custom_prompt": {
"type": "boolean",
"description": "Not read at the top level. Respan reads `is_custom_prompt` only inside a `prompt` object, as in `{\"prompt\": {\"prompt_id\": \"your-id\", \"is_custom_prompt\": true}}`. Set it there for a prompt you manage outside Respan. Otherwise Respan looks up `prompt.prompt_id` among your saved prompts and rejects the span if none matches. A top-level `prompt_id` is logged as sent and isn't looked up.",
"default": false,
"example": false
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the request started.",
"example": "2025-03-15T10:29:59Z"
},
"full_request": {
"type": "object",
"description": "Full raw request object for reference."
},
"full_response": {
"type": "object",
"description": "Full raw response object from the provider."
},
"prompt_unit_price": {
"type": "number",
"description": "Custom price per 1M prompt tokens (for self-hosted/fine-tuned models).",
"example": 2.5
},
"completion_unit_price": {
"type": "number",
"description": "Custom price per 1M completion tokens (for self-hosted/fine-tuned models).",
"example": 10
},
"respan_params": {
"type": "object",
"description": "Preferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags."
},
"keywordsai_params": {
"type": "object",
"description": "Legacy alias for `respan_params`. Still accepted and merged into `respan_params`."
},
"positive_feedback": {
"type": "boolean",
"description": "User feedback. `true` = positive, `false` = negative.",
"example": true
},
"error_code": {
"type": "string",
"maxLength": 120,
"description": "Normalized application or provider error code."
}
},
"required": [
"model"
]
}
},
"securitySchemes": {
"RespanApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Respan API key",
"description": "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.",
"x-fern-bearer": {
"name": "respanApiKey",
"env": "RESPAN_API_KEY"
}
}
}
}