Create spans in bulk
https://api.respan.ai/api/request-logs/bulk/Accepts up to 500 spans per request. Each item in logs uses the fields in Create a span. Rows are processed independently. A 201 Created response means at least one row was accepted, so check error_count and errors for partial failures. success_count counts rows that passed synchronous validation and were accepted for ingestion.
Rate limit: 30 requests per minute per organization for API-key calls, shared across the organization’s keys. For JWT calls, the limit is per user. 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_KEYOr:
DashboardJwt
Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.
HTTP scheme: bearer; format: Dashboard JWT.
Authorization: Bearer $RESPAN_DASHBOARD_JWTRequest body
A request body is required.
application/json
$ object Required body
logs array<object> Required in parent
POST /api/request-logs/.Minimum items:
1Maximum items:
500logs[] object Array item
#/components/schemas/SpanCreateRequestlogs[].model string Required in parentExample:
"gpt-4o-mini"logs[].prompt_messages array<object> Optional
Example:
[{"role":"user","content":"Hello"}]logs[].prompt_messages[] object Array itemlogs[].completion_message object OptionalExample:
{"role":"assistant","content":"Hi there!"}logs[].prompt_tokens integer Optionalinput_tokens before cache-token normalization.Example:
50logs[].completion_tokens integer Optionaloutput_tokens.Example:
100logs[].usage object Optional
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}logs[].usage.prompt_tokens integer Optionallogs[].usage.completion_tokens integer Optionallogs[].usage.total_tokens integer Optionallogs[].usage.input_tokens integer Optionallogs[].usage.output_tokens integer Optionallogs[].usage.cache_creation_input_tokens integer Optionalprompt_cache_creation_tokens.logs[].usage.cache_read_input_tokens integer Optionalprompt_cache_hit_tokens.logs[].temperature number OptionalDefault:
1Example:
0.7logs[].top_p number OptionalDefault:
1Example:
1logs[].max_tokens integer OptionalExample:
1024logs[].generation_time number Optionallatency in responses and query results.Example:
1.23logs[].ttft number Optionaltime_to_first_token in responses and query results.Example:
0.35logs[].customer_params object Optional
customer_identifier inside this object is promoted to the log customer identifier.Example:
{"customer_identifier":"user_123","email":"alice@example.com","name":"Alice"}logs[].customer_params.customer_identifier string Optionallogs[].customer_params.email string Optionallogs[].customer_params.name string Optionallogs[].metadata object Optional_ are reserved and omitted from customer-facing read responses.Example:
{"env":"production","feature":"chat"}logs[].environment string OptionalAllowed:
"prod", "test"Read only
Example:
"prod"logs[].stream boolean OptionalDefault:
falseExample:
falselogs[].status_code integer OptionalDefault:
200Example:
200logs[].tools array<object> Optional
Example:
[{"type":"function","function":{"name":"lookup_order","description":"Lookup an order by ID"}}]logs[].tools[] object Array itemlogs[].tool_calls array<object> Optional
Example:
[{"id":"call_abc123","type":"function","function":{"name":"lookup_order","arguments":"{\"order_id\":\"ord_123\"}"}}]logs[].tool_calls[] object Array itemlogs[].timestamp string OptionalFormat:
date-timeExample:
"2025-03-15T10:30:00Z"logs[].trace_unique_id string OptionalExample:
"trace_abc123"logs[].span_name string OptionalExample:
"classify_intent"logs[].span_parent_id string OptionalExample:
"span_parent_001"logs[].span_workflow_name string OptionalExample:
"customer_support_flow"logs[].custom_identifier string OptionalExample:
"order_456"logs[].thread_identifier string OptionalExample:
"thread_abc"logs[].group_identifier string OptionalExample:
"batch_789"logs[].latency number Optionalgeneration_time is also accepted and normalizes to this field.Example:
1.23logs[].time_to_first_token number Optionalttft is also accepted and normalizes to this field.Example:
0.35logs[].log_type string Optionalinput and output are parsed.Allowed:
"chat", "completion", "response", "embedding", "speech", "transcription", "workflow", "agent", "task", "tool", "guardrail", "reranker", "other"Default:
chatExample:
"chat"logs[].input string or object or array<object> Optional
Example:
"[{\"role\": \"user\", \"content\": \"Hello\"}]"logs[].input (oneOf 1) string Schema variantlogs[].input (oneOf 2) object Schema variantlogs[].input (oneOf 3) array<object> Schema variant
logs[].input (oneOf 3)[] object Array itemlogs[].output string or object or array<object> Optional
Example:
"{\"role\": \"assistant\", \"content\": \"Hi there!\"}"logs[].output (oneOf 1) string Schema variantlogs[].output (oneOf 2) object Schema variantlogs[].output (oneOf 3) array<object> Schema variant
logs[].output (oneOf 3)[] object Array itemlogs[].messages array<object> Optional
prompt_messages; prefer input for new integrations.Example:
[{"role":"user","content":"Hello"}]logs[].messages[] object Array itemlogs[].cost number OptionalExample:
0.0025logs[].tokens_per_second number OptionalExample:
45.2logs[].properties object OptionalExample:
{"cache_hit":false,"score":0.98}logs[].variables object OptionalExample:
{"customer_name":"Alice"}logs[].customer_identifier string OptionalMaximum length:
254Example:
"user_123"logs[].tool_choice string or object Optional
"none", "auto", or a specific tool object.logs[].tool_choice (oneOf 1) string Schema variantlogs[].tool_choice (oneOf 2) object Schema variantlogs[].response_format object Optionallogs[].frequency_penalty number OptionalExample:
0logs[].presence_penalty number OptionalExample:
0logs[].stop string or array<string> Optional
logs[].stop (oneOf 1) string Schema variantlogs[].stop (oneOf 2) array<string> Schema variant
logs[].stop (oneOf 2)[] string Array itemlogs[].error_message string OptionalExample:
""logs[].warnings string or object Optional
logs[].warnings (oneOf 1) string Schema variantlogs[].warnings (oneOf 2) object Schema variantlogs[].status string Optionalerror is stored as failed.Allowed:
"success", "error"Example:
"success"logs[].prompt_id string OptionalExample:
"prompt_abc123"logs[].prompt_name string OptionalExample:
"customer_support"logs[].is_custom_prompt boolean Optionalis_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:
falselogs[].start_time string OptionalFormat:
date-timeExample:
"2025-03-15T10:29:59Z"logs[].full_request object Optionallogs[].full_response object Optionallogs[].prompt_unit_price number OptionalExample:
2.5logs[].completion_unit_price number OptionalExample:
10logs[].respan_params object Optionallogs[].keywordsai_params object Optionalrespan_params. Still accepted and merged into respan_params.logs[].positive_feedback boolean Optionaltrue = positive, false = negative.Example:
truelogs[].error_code string OptionalMaximum length:
120OpenAPI request schema
{
"type": "object",
"required": [
"logs"
],
"properties": {
"logs": {
"type": "array",
"description": "Non-empty array of span payloads. Each object uses the same schema as `POST /api/request-logs/`.",
"minItems": 1,
"maxItems": 500,
"items": {
"$ref": "#/components/schemas/SpanCreateRequest"
}
}
}
}All rows accepted
{
"logs": [
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is 2 + 2?"
}
],
"completion_message": {
"role": "assistant",
"content": "4"
},
"metadata": {
"source": "lambda-batch"
}
},
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is the capital of France?"
}
],
"completion_message": {
"role": "assistant",
"content": "Paris"
},
"metadata": {
"source": "lambda-batch"
}
}
]
}One row rejected
{
"logs": [
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is 2 + 2?"
}
],
"completion_message": {
"role": "assistant",
"content": "4"
},
"metadata": {
"source": "lambda-batch"
}
},
{
"model": "gpt-4o-mini",
"prompt_messages": [
{}
]
}
]
}Examples
All rows accepted
Headers
{
"Authorization": "Bearer YOUR_RESPAN_API_KEY"
}Request
{
"logs": [
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is 2 + 2?"
}
],
"completion_message": {
"role": "assistant",
"content": "4"
},
"metadata": {
"source": "lambda-batch"
}
},
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is the capital of France?"
}
],
"completion_message": {
"role": "assistant",
"content": "Paris"
},
"metadata": {
"source": "lambda-batch"
}
}
]
}Response
{
"body": {
"success_count": 2,
"error_count": 0,
"errors": []
}
}One row rejected
Headers
{
"Authorization": "Bearer YOUR_RESPAN_API_KEY"
}Request
{
"logs": [
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is 2 + 2?"
}
],
"completion_message": {
"role": "assistant",
"content": "4"
},
"metadata": {
"source": "lambda-batch"
}
},
{
"model": "gpt-4o-mini",
"prompt_messages": [
{}
]
}
]
}Response
{
"body": {
"success_count": 1,
"error_count": 1,
"errors": [
{
"index": 1,
"error": "Invalid logging format: Field required"
}
]
}
}Responses
201
At least one row was accepted. This status is also used for partial success; inspect the response counts and indexed errors.
application/json
$ object Body
Reference:
#/components/schemas/BulkOperationResponseExample:
{"success_count":1,"error_count":0,"errors":[]}success_count integer Required in parentMinimum:
0error_count integer Required in parentMinimum:
0errors array<object> Required in parent
errors[] object Array item
index is zero-based and identifies the corresponding item in the request array.Reference:
#/components/schemas/BulkItemErrorerrors[].index integer Required in parentMinimum:
0errors[].error string Required in parentOpenAPI response schema
{
"$ref": "#/components/schemas/BulkOperationResponse"
}All rows accepted
{
"success_count": 2,
"error_count": 0,
"errors": []
}One row rejected
{
"success_count": 1,
"error_count": 1,
"errors": [
{
"index": 1,
"error": "Invalid logging format: Field required"
}
]
}400
Every row failed, the logs envelope was missing or malformed, the list was empty, or the organization is blocked.
application/json
$ object or object Body
$ (anyOf 1) object Schema variant
Reference:
#/components/schemas/BulkOperationResponseExample:
{"success_count":1,"error_count":0,"errors":[]}$ (anyOf 1).success_count integer Required in parentMinimum:
0$ (anyOf 1).error_count integer Required in parentMinimum:
0$ (anyOf 1).errors array<object> Required in parent
$ (anyOf 1).errors[] object Array item
index is zero-based and identifies the corresponding item in the request array.Reference:
#/components/schemas/BulkItemError$ (anyOf 1).errors[].index integer Required in parentMinimum:
0$ (anyOf 1).errors[].error string Required in parent$ (anyOf 2) object Schema variantAdditional properties are allowed
OpenAPI response schema
{
"anyOf": [
{
"$ref": "#/components/schemas/BulkOperationResponse"
},
{
"type": "object",
"description": "Serializer or organization-level error response.",
"additionalProperties": true
}
]
}All rows failed
{
"success_count": 0,
"error_count": 1,
"errors": [
{
"index": 0,
"error": "Invalid logging format: Field required"
}
]
}Empty batch
{
"logs": [
"This list may not be empty."
]
}Blocked organization
{
"detail": "Your organization has been banned from creating logs."
}403
The API key is missing, invalid or expired, or it can’t access this organization.
application/json
$ object Body
detail string Required in parentOpenAPI 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
The batch contains more than 500 rows.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Cannot process more than 500 items at once."
}429
Rate limit exceeded.
application/json
$ object Body
detail string OptionalOpenAPI response schema
{
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"additionalProperties": true
}Example
{
"detail": "Rate limit exceeded. Please try again later."
}OpenAPI source
The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.
OpenAPI operation
{
"summary": "Create spans in bulk",
"operationId": "bulkCreateSpans",
"tags": [
"Spans"
],
"description": "Accepts up to 500 spans per request. Each item in `logs` uses the fields in [Create a span](/docs/apis/spans/create-span). Rows are processed independently. A `201 Created` response means at least one row was accepted, so check `error_count` and `errors` for partial failures. `success_count` counts rows that passed synchronous validation and were accepted for ingestion.\n\nRate limit: 30 requests per minute per organization for API-key calls, shared across the organization's keys. For JWT calls, the limit is per user. Metadata keys beginning with `_` are reserved for platform use and omitted from span and trace read responses.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"logs"
],
"properties": {
"logs": {
"type": "array",
"description": "Non-empty array of span payloads. Each object uses the same schema as `POST /api/request-logs/`.",
"minItems": 1,
"maxItems": 500,
"items": {
"$ref": "#/components/schemas/SpanCreateRequest"
}
}
}
},
"examples": {
"allAccepted": {
"summary": "All rows accepted",
"value": {
"logs": [
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is 2 + 2?"
}
],
"completion_message": {
"role": "assistant",
"content": "4"
},
"metadata": {
"source": "lambda-batch"
}
},
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is the capital of France?"
}
],
"completion_message": {
"role": "assistant",
"content": "Paris"
},
"metadata": {
"source": "lambda-batch"
}
}
]
}
},
"partialSuccess": {
"summary": "One row rejected",
"value": {
"logs": [
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is 2 + 2?"
}
],
"completion_message": {
"role": "assistant",
"content": "4"
},
"metadata": {
"source": "lambda-batch"
}
},
{
"model": "gpt-4o-mini",
"prompt_messages": [
{}
]
}
]
}
}
}
}
}
},
"responses": {
"201": {
"description": "At least one row was accepted. This status is also used for partial success; inspect the response counts and indexed errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkOperationResponse"
},
"examples": {
"allAccepted": {
"summary": "All rows accepted",
"value": {
"success_count": 2,
"error_count": 0,
"errors": []
}
},
"partialSuccess": {
"summary": "One row rejected",
"value": {
"success_count": 1,
"error_count": 1,
"errors": [
{
"index": 1,
"error": "Invalid logging format: Field required"
}
]
}
}
}
}
}
},
"400": {
"description": "Every row failed, the `logs` envelope was missing or malformed, the list was empty, or the organization is blocked.",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/BulkOperationResponse"
},
{
"type": "object",
"description": "Serializer or organization-level error response.",
"additionalProperties": true
}
]
},
"examples": {
"allRowsFailed": {
"summary": "All rows failed",
"value": {
"success_count": 0,
"error_count": 1,
"errors": [
{
"index": 0,
"error": "Invalid logging format: Field required"
}
]
}
},
"emptyBatch": {
"summary": "Empty batch",
"value": {
"logs": [
"This list may not be empty."
]
}
},
"blockedOrganization": {
"summary": "Blocked organization",
"value": {
"detail": "Your organization has been banned from creating logs."
}
}
}
}
}
},
"403": {
"description": "The API key is missing, invalid or expired, or it can't access this organization.",
"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."
}
}
}
},
"422": {
"description": "The batch contains more than 500 rows.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Cannot process more than 500 items at once."
}
}
}
},
"429": {
"description": "Rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"detail": {
"type": "string"
}
},
"additionalProperties": true
},
"example": {
"detail": "Rate limit exceeded. Please try again later."
}
}
}
}
},
"security": [
{
"RespanApiKey": []
},
{
"DashboardJwt": []
}
],
"x-fern-examples": [
{
"name": "All rows accepted",
"request": {
"logs": [
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is 2 + 2?"
}
],
"completion_message": {
"role": "assistant",
"content": "4"
},
"metadata": {
"source": "lambda-batch"
}
},
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is the capital of France?"
}
],
"completion_message": {
"role": "assistant",
"content": "Paris"
},
"metadata": {
"source": "lambda-batch"
}
}
]
},
"response": {
"body": {
"success_count": 2,
"error_count": 0,
"errors": []
}
},
"headers": {
"Authorization": "Bearer YOUR_RESPAN_API_KEY"
}
},
{
"name": "One row rejected",
"request": {
"logs": [
{
"model": "gpt-4o-mini",
"prompt_messages": [
{
"role": "user",
"content": "What is 2 + 2?"
}
],
"completion_message": {
"role": "assistant",
"content": "4"
},
"metadata": {
"source": "lambda-batch"
}
},
{
"model": "gpt-4o-mini",
"prompt_messages": [
{}
]
}
]
},
"response": {
"body": {
"success_count": 1,
"error_count": 1,
"errors": [
{
"index": 1,
"error": "Invalid logging format: Field required"
}
]
}
},
"headers": {
"Authorization": "Bearer YOUR_RESPAN_API_KEY"
}
}
]
}OpenAPI path metadata
{}Referenced OpenAPI components
{
"schemas": {
"BulkItemError": {
"type": "object",
"description": "An item that failed during a bulk operation. `index` is zero-based and identifies the corresponding item in the request array.",
"required": [
"index",
"error"
],
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"description": "Zero-based index of the failed item in the submitted array."
},
"error": {
"type": "string",
"description": "Error message for the failed item."
}
}
},
"BulkOperationResponse": {
"type": "object",
"description": "Canonical result envelope for a bulk operation.",
"required": [
"success_count",
"error_count",
"errors"
],
"properties": {
"success_count": {
"type": "integer",
"minimum": 0,
"description": "Number of items successfully processed."
},
"error_count": {
"type": "integer",
"minimum": 0,
"description": "Number of items that failed."
},
"errors": {
"type": "array",
"description": "Item-level failures, keyed by zero-based input index.",
"items": {
"$ref": "#/components/schemas/BulkItemError"
}
}
},
"example": {
"success_count": 1,
"error_count": 0,
"errors": []
}
},
"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": {
"DashboardJwt": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Dashboard JWT",
"description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
"x-fern-bearer": {
"name": "dashboardJwt",
"env": "RESPAN_DASHBOARD_JWT"
}
},
"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"
}
}
}
}