Skip to Content

Create spans in bulk

POSThttps://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.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Or:

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.

HTTP
Authorization: Bearer $RESPAN_DASHBOARD_JWT

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
-
logs array<object> Required in parent
Non-empty array of span payloads. Each object uses the same schema as POST /api/request-logs/.
Minimum items: 1
Maximum items: 500
logs[] object Array item
Reference: #/components/schemas/SpanCreateRequest
logs[].model string Required in parent
Model used for the span.
Example: "gpt-4o-mini"
logs[].prompt_messages array<object> Optional
Chat input messages for the request log.
Example: [{"role":"user","content":"Hello"}]
logs[].prompt_messages[] object Array item
-
logs[].completion_message object Optional
Assistant message returned by the model.
Example: {"role":"assistant","content":"Hi there!"}
logs[].prompt_tokens integer Optional
Prompt/input tokens for the request. For Anthropic logs this corresponds to input_tokens before cache-token normalization.
Example: 50
logs[].completion_tokens integer Optional
Completion/output tokens for the request. For Anthropic logs this corresponds to output_tokens.
Example: 100
logs[].usage object Optional
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.
Example: {"cache_creation_input_tokens":0,"cache_read_input_tokens":0}
logs[].usage.prompt_tokens integer Optional
-
logs[].usage.completion_tokens integer Optional
-
logs[].usage.total_tokens integer Optional
-
logs[].usage.input_tokens integer Optional
Anthropic input token count.
logs[].usage.output_tokens integer Optional
Anthropic output token count.
logs[].usage.cache_creation_input_tokens integer Optional
Anthropic cache-creation input tokens. Normalized to prompt_cache_creation_tokens.
logs[].usage.cache_read_input_tokens integer Optional
Anthropic cache-read input tokens. Normalized to prompt_cache_hit_tokens.
logs[].temperature number Optional
Sampling temperature (0-2). Higher = more random.
Default: 1
Example: 0.7
logs[].top_p number Optional
Nucleus sampling parameter.
Default: 1
Example: 1
logs[].max_tokens integer Optional
Maximum tokens to generate.
Example: 1024
logs[].generation_time number Optional
Accepted alias for total generation latency in seconds. Stored as latency in responses and query results.
Example: 1.23
logs[].ttft number Optional
Accepted alias for time to first token in seconds. Stored as time_to_first_token in responses and query results.
Example: 0.35
logs[].customer_params object Optional
Extended customer information. 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 Optional
-
logs[].customer_params.email string Optional
-
logs[].customer_params.name string Optional
-
logs[].metadata object Optional
Arbitrary customer metadata. Keys beginning with _ are reserved and omitted from customer-facing read responses.
Example: {"env":"production","feature":"chat"}
logs[].environment string Optional
Stored environment for the log. This is derived from the API key environment; body-supplied values do not override a prod/test key.
Allowed: "prod", "test"
Read only
Example: "prod"
logs[].stream boolean Optional
Whether the response was streamed.
Default: false
Example: false
logs[].status_code integer Optional
HTTP status code of the request.
Default: 200
Example: 200
logs[].tools array<object> Optional
Tools available to the model (OpenAI function calling format).
Example: [{"type":"function","function":{"name":"lookup_order","description":"Lookup an order by ID"}}]
logs[].tools[] object Array item
-
logs[].tool_calls array<object> Optional
Tool calls returned by the model.
Example: [{"id":"call_abc123","type":"function","function":{"name":"lookup_order","arguments":"{\"order_id\":\"ord_123\"}"}}]
logs[].tool_calls[] object Array item
-
logs[].timestamp string Optional
ISO 8601 timestamp when the request completed.
Format: date-time
Example: "2025-03-15T10:30:00Z"
logs[].trace_unique_id string Optional
Trace ID to link spans into a trace tree.
Example: "trace_abc123"
logs[].span_name string Optional
Name of this span within the workflow.
Example: "classify_intent"
logs[].span_parent_id string Optional
Parent span ID. Builds the trace hierarchy.
Example: "span_parent_001"
logs[].span_workflow_name string Optional
Name of the parent workflow.
Example: "customer_support_flow"
logs[].custom_identifier string Optional
Indexed custom identifier for fast querying.
Example: "order_456"
logs[].thread_identifier string Optional
Conversation thread ID for multi-turn conversations.
Example: "thread_abc"
logs[].group_identifier string Optional
Groups related spans together.
Example: "batch_789"
logs[].latency number Optional
Total request latency in seconds. generation_time is also accepted and normalizes to this field.
Example: 1.23
logs[].time_to_first_token number Optional
Time to first token in seconds. ttft is also accepted and normalizes to this field.
Example: 0.35
logs[].log_type string Optional
Type of span. Determines how input and output are parsed.
Allowed: "chat", "completion", "response", "embedding", "speech", "transcription", "workflow", "agent", "task", "tool", "guardrail", "reranker", "other"
Default: chat
Example: "chat"
logs[].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: "[{\"role\": \"user\", \"content\": \"Hello\"}]"
logs[].input (oneOf 1) string Schema variant
-
logs[].input (oneOf 2) object Schema variant
-
logs[].input (oneOf 3) array<object> Schema variant
-
logs[].input (oneOf 3)[] object Array item
-
logs[].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: "{\"role\": \"assistant\", \"content\": \"Hi there!\"}"
logs[].output (oneOf 1) string Schema variant
-
logs[].output (oneOf 2) object Schema variant
-
logs[].output (oneOf 3) array<object> Schema variant
-
logs[].output (oneOf 3)[] object Array item
-
logs[].messages array<object> Optional
Legacy chat input field. Equivalent to prompt_messages; prefer input for new integrations.
Example: [{"role":"user","content":"Hello"}]
logs[].messages[] object Array item
-
logs[].cost number Optional
Cost in USD. Auto-calculated from model pricing if omitted.
Example: 0.0025
logs[].tokens_per_second number Optional
Generation speed in tokens per second.
Example: 45.2
logs[].properties object Optional
Typed metadata that preserves native JSON types.
Example: {"cache_hit":false,"score":0.98}
logs[].variables object Optional
Variables used for prompt templates.
Example: {"customer_name":"Alice"}
logs[].customer_identifier string Optional
Identifier for the end user who made this request.
Maximum length: 254
Example: "user_123"
logs[].tool_choice string or object Optional
Controls tool selection. "none", "auto", or a specific tool object.
logs[].tool_choice (oneOf 1) string Schema variant
-
logs[].tool_choice (oneOf 2) object Schema variant
-
logs[].response_format object Optional
Response format configuration (e.g. JSON mode or structured output).
logs[].frequency_penalty number Optional
Penalizes repeated tokens (-2 to 2).
Example: 0
logs[].presence_penalty number Optional
Penalizes tokens already present (-2 to 2).
Example: 0
logs[].stop string or array<string> Optional
Stop sequence or sequences where generation halts.
logs[].stop (oneOf 1) string Schema variant
-
logs[].stop (oneOf 2) array<string> Schema variant
-
logs[].stop (oneOf 2)[] string Array item
-
logs[].error_message string Optional
Error message if the request failed.
Example: ""
logs[].warnings string or object Optional
Warnings from the request.
logs[].warnings (oneOf 1) string Schema variant
-
logs[].warnings (oneOf 2) object Schema variant
-
logs[].status string Optional
Request status. error is stored as failed.
Allowed: "success", "error"
Example: "success"
logs[].prompt_id string Optional
ID of the Respan prompt template used.
Example: "prompt_abc123"
logs[].prompt_name string Optional
Name of the prompt template.
Example: "customer_support"
logs[].is_custom_prompt boolean Optional
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
logs[].start_time string Optional
ISO 8601 timestamp when the request started.
Format: date-time
Example: "2025-03-15T10:29:59Z"
logs[].full_request object Optional
Full raw request object for reference.
logs[].full_response object Optional
Full raw response object from the provider.
logs[].prompt_unit_price number Optional
Custom price per 1M prompt tokens (for self-hosted/fine-tuned models).
Example: 2.5
logs[].completion_unit_price number Optional
Custom price per 1M completion tokens (for self-hosted/fine-tuned models).
Example: 10
logs[].respan_params object Optional
Preferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags.
logs[].keywordsai_params object Optional
Legacy alias for respan_params. Still accepted and merged into respan_params.
logs[].positive_feedback boolean Optional
User feedback. true = positive, false = negative.
Example: true
logs[].error_code string Optional
Normalized application or provider error code.
Maximum length: 120

OpenAPI 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
JSON
{ "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
JSON
{ "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

JSON
{ "Authorization": "Bearer YOUR_RESPAN_API_KEY" }

Request

JSON
{ "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

JSON
{ "body": { "success_count": 2, "error_count": 0, "errors": [] } }

One row rejected

Headers

JSON
{ "Authorization": "Bearer YOUR_RESPAN_API_KEY" }

Request

JSON
{ "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

JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
Canonical result envelope for a bulk operation.
Reference: #/components/schemas/BulkOperationResponse
Example: {"success_count":1,"error_count":0,"errors":[]}
success_count integer Required in parent
Number of items successfully processed.
Minimum: 0
error_count integer Required in parent
Number of items that failed.
Minimum: 0
errors array<object> Required in parent
Item-level failures, keyed by zero-based input index.
errors[] object Array item
An item that failed during a bulk operation. index is zero-based and identifies the corresponding item in the request array.
Reference: #/components/schemas/BulkItemError
errors[].index integer Required in parent
Zero-based index of the failed item in the submitted array.
Minimum: 0
errors[].error string Required in parent
Error message for the failed item.

OpenAPI response schema

{
  "$ref": "#/components/schemas/BulkOperationResponse"
}
All rows accepted
JSON
{ "success_count": 2, "error_count": 0, "errors": [] }
One row rejected
JSON
{ "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

Field Type Requirement Description and constraints
$ object or object Body
-
$ (anyOf 1) object Schema variant
Canonical result envelope for a bulk operation.
Reference: #/components/schemas/BulkOperationResponse
Example: {"success_count":1,"error_count":0,"errors":[]}
$ (anyOf 1).success_count integer Required in parent
Number of items successfully processed.
Minimum: 0
$ (anyOf 1).error_count integer Required in parent
Number of items that failed.
Minimum: 0
$ (anyOf 1).errors array<object> Required in parent
Item-level failures, keyed by zero-based input index.
$ (anyOf 1).errors[] object Array item
An item that failed during a bulk operation. index is zero-based and identifies the corresponding item in the request array.
Reference: #/components/schemas/BulkItemError
$ (anyOf 1).errors[].index integer Required in parent
Zero-based index of the failed item in the submitted array.
Minimum: 0
$ (anyOf 1).errors[].error string Required in parent
Error message for the failed item.
$ (anyOf 2) object Schema variant
Serializer or organization-level error response.
Additional 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
JSON
{ "success_count": 0, "error_count": 1, "errors": [ { "index": 0, "error": "Invalid logging format: Field required" } ] }
Empty batch
JSON
{ "logs": [ "This list may not be empty." ] }
Blocked organization
JSON
{ "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

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
JSON
{ "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

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
JSON
{ "detail": "Cannot process more than 500 items at once." }

429

Rate limit exceeded.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed
detail string Optional
-

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string"
    }
  },
  "additionalProperties": true
}
Example
JSON
{ "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"
      }
    }
  }
}