Skip to Content

Ingest spans (legacy)

POSThttps://api.respan.ai/api/v1/traces/ingest

Accepts spans as a JSON array or an object whose data field contains the array. Each span uses the fields in Create a span, plus trace_unique_id, span_unique_id, and optional span_parent_id to build the trace tree. For new integrations, use Ingest traces (OTLP).

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

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ array<object> or object Required body
-
$ (oneOf 1) array<object> Schema variant
Array of span objects to ingest as traces.
$ (oneOf 1)[] object Array item
-
$ (oneOf 1)[].trace_unique_id string Required in parent
Trace ID linking all spans.
Example: "trace_abc123"
$ (oneOf 1)[].span_unique_id string Required in parent
Unique ID for this span.
Example: "span_001"
$ (oneOf 1)[].span_parent_id string or null Optional
Parent span ID. null for root spans.
Example: null
$ (oneOf 1)[].span_name string Optional
Name of this span.
Example: "llm_call"
$ (oneOf 1)[].span_workflow_name string Optional
Workflow name.
Example: "support_flow"
$ (oneOf 1)[].log_type string Optional
Span type.
Allowed: "chat", "completion", "response", "embedding", "speech", "transcription", "workflow", "agent", "task", "tool", "guardrail", "reranker", "other"
Default: chat
Example: "chat"
$ (oneOf 1)[].input any Optional
Input to the model.
Example: "[{\"role\": \"user\", \"content\": \"Hello\"}]"
$ (oneOf 1)[].output any Optional
Output from the model.
Example: "{\"role\": \"assistant\", \"content\": \"Hi!\"}"
$ (oneOf 1)[].model string Optional
Model used.
Example: "gpt-4o"
$ (oneOf 1)[].usage object Optional
Token usage.
Example: {"prompt_tokens":10,"completion_tokens":8,"total_tokens":18}
$ (oneOf 1)[].cost number Optional
Cost in USD.
Example: 0.001
$ (oneOf 1)[].latency number Optional
Latency in seconds.
Example: 1.2
$ (oneOf 1)[].status string Optional
Allowed: "success", "error"
Example: "success"
$ (oneOf 1)[].timestamp string Optional
When completed (ISO 8601).
Format: date-time
Example: "2025-01-15T10:30:00Z"
$ (oneOf 1)[].start_time string Optional
When started (ISO 8601).
Format: date-time
Example: "2025-01-15T10:29:59Z"
$ (oneOf 1)[].customer_identifier string Optional
End user identifier.
Example: "user_123"
$ (oneOf 1)[].metadata object Optional
Arbitrary key-value pairs.
Example: {"env":"production"}
$ (oneOf 1)[].span_path string Optional
Nested path within the workflow.
Example: "joke_creation.store_joke"
$ (oneOf 1)[].encoding_format string Optional
Embedding encoding format for embedding spans.
Example: "float"
$ (oneOf 1)[].provider_id string Optional
LLM or service provider ID.
Example: "openai"
$ (oneOf 1)[].prompt_tokens integer Optional
Number of prompt tokens used.
Example: 150
$ (oneOf 1)[].completion_tokens integer Optional
Number of completion tokens used.
Example: 80
$ (oneOf 1)[].warnings string Optional
Warnings captured during span execution.
$ (oneOf 1)[].disable_log boolean Optional
Set true to disable logging for this span.
Default: false
$ (oneOf 1)[].respan_params object Optional
Additional Respan parameters (e.g. has_webhook, environment).
$ (oneOf 1)[].temperature number Optional
LLM temperature (0-2).
Example: 0.7
$ (oneOf 1)[].presence_penalty number Optional
Presence penalty for LLM requests.
Example: 0
$ (oneOf 1)[].frequency_penalty number Optional
Frequency penalty for LLM requests.
Example: 0
$ (oneOf 1)[].max_tokens integer Optional
Maximum tokens for completion.
Example: 1024
$ (oneOf 1)[].stream boolean Optional
Whether the response was streamed.
Default: false
$ (oneOf 2) object Schema variant
Wrapper object accepted by the legacy integration endpoint.
$ (oneOf 2).data array<object> Required in parent
Array of span objects to ingest as traces.
$ (oneOf 2).data[] object Array item
-
$ (oneOf 2).data[].trace_unique_id string Required in parent
Trace ID linking all spans.
Example: "trace_abc123"
$ (oneOf 2).data[].span_unique_id string Required in parent
Unique ID for this span.
Example: "span_001"
$ (oneOf 2).data[].span_parent_id string or null Optional
Parent span ID. null for root spans.
Example: null
$ (oneOf 2).data[].span_name string Optional
Name of this span.
Example: "llm_call"
$ (oneOf 2).data[].span_workflow_name string Optional
Workflow name.
Example: "support_flow"
$ (oneOf 2).data[].log_type string Optional
Span type.
Allowed: "chat", "completion", "response", "embedding", "speech", "transcription", "workflow", "agent", "task", "tool", "guardrail", "reranker", "other"
Default: chat
Example: "chat"
$ (oneOf 2).data[].input any Optional
Input to the model.
Example: "[{\"role\": \"user\", \"content\": \"Hello\"}]"
$ (oneOf 2).data[].output any Optional
Output from the model.
Example: "{\"role\": \"assistant\", \"content\": \"Hi!\"}"
$ (oneOf 2).data[].model string Optional
Model used.
Example: "gpt-4o"
$ (oneOf 2).data[].usage object Optional
Token usage.
Example: {"prompt_tokens":10,"completion_tokens":8,"total_tokens":18}
$ (oneOf 2).data[].cost number Optional
Cost in USD.
Example: 0.001
$ (oneOf 2).data[].latency number Optional
Latency in seconds.
Example: 1.2
$ (oneOf 2).data[].status string Optional
Allowed: "success", "error"
Example: "success"
$ (oneOf 2).data[].timestamp string Optional
When completed (ISO 8601).
Format: date-time
Example: "2025-01-15T10:30:00Z"
$ (oneOf 2).data[].start_time string Optional
When started (ISO 8601).
Format: date-time
Example: "2025-01-15T10:29:59Z"
$ (oneOf 2).data[].customer_identifier string Optional
End user identifier.
Example: "user_123"
$ (oneOf 2).data[].metadata object Optional
Arbitrary key-value pairs.
Example: {"env":"production"}
$ (oneOf 2).data[].span_path string Optional
Nested path within the workflow.
Example: "joke_creation.store_joke"
$ (oneOf 2).data[].encoding_format string Optional
Embedding encoding format for embedding spans.
Example: "float"
$ (oneOf 2).data[].provider_id string Optional
LLM or service provider ID.
Example: "openai"
$ (oneOf 2).data[].prompt_tokens integer Optional
Number of prompt tokens used.
Example: 150
$ (oneOf 2).data[].completion_tokens integer Optional
Number of completion tokens used.
Example: 80
$ (oneOf 2).data[].warnings string Optional
Warnings captured during span execution.
$ (oneOf 2).data[].disable_log boolean Optional
Set true to disable logging for this span.
Default: false
$ (oneOf 2).data[].respan_params object Optional
Additional Respan parameters (e.g. has_webhook, environment).
$ (oneOf 2).data[].temperature number Optional
LLM temperature (0-2).
Example: 0.7
$ (oneOf 2).data[].presence_penalty number Optional
Presence penalty for LLM requests.
Example: 0
$ (oneOf 2).data[].frequency_penalty number Optional
Frequency penalty for LLM requests.
Example: 0
$ (oneOf 2).data[].max_tokens integer Optional
Maximum tokens for completion.
Example: 1024
$ (oneOf 2).data[].stream boolean Optional
Whether the response was streamed.
Default: false

OpenAPI request schema

{
  "oneOf": [
    {
      "type": "array",
      "description": "Array of span objects to ingest as traces.",
      "items": {
        "type": "object",
        "required": [
          "trace_unique_id",
          "span_unique_id"
        ],
        "properties": {
          "trace_unique_id": {
            "type": "string",
            "description": "Trace ID linking all spans.",
            "example": "trace_abc123"
          },
          "span_unique_id": {
            "type": "string",
            "description": "Unique ID for this span.",
            "example": "span_001"
          },
          "span_parent_id": {
            "type": "string",
            "nullable": true,
            "description": "Parent span ID. `null` for root spans.",
            "example": null
          },
          "span_name": {
            "type": "string",
            "description": "Name of this span.",
            "example": "llm_call"
          },
          "span_workflow_name": {
            "type": "string",
            "description": "Workflow name.",
            "example": "support_flow"
          },
          "log_type": {
            "type": "string",
            "description": "Span type.",
            "enum": [
              "chat",
              "completion",
              "response",
              "embedding",
              "speech",
              "transcription",
              "workflow",
              "agent",
              "task",
              "tool",
              "guardrail",
              "reranker",
              "other"
            ],
            "default": "chat",
            "example": "chat"
          },
          "input": {
            "description": "Input to the model.",
            "example": "[{\"role\": \"user\", \"content\": \"Hello\"}]"
          },
          "output": {
            "description": "Output from the model.",
            "example": "{\"role\": \"assistant\", \"content\": \"Hi!\"}"
          },
          "model": {
            "type": "string",
            "description": "Model used.",
            "example": "gpt-4o"
          },
          "usage": {
            "type": "object",
            "description": "Token usage.",
            "example": {
              "prompt_tokens": 10,
              "completion_tokens": 8,
              "total_tokens": 18
            }
          },
          "cost": {
            "type": "number",
            "description": "Cost in USD.",
            "example": 0.001
          },
          "latency": {
            "type": "number",
            "description": "Latency in seconds.",
            "example": 1.2
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "example": "success"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When completed (ISO 8601).",
            "example": "2025-01-15T10:30:00Z"
          },
          "start_time": {
            "type": "string",
            "format": "date-time",
            "description": "When started (ISO 8601).",
            "example": "2025-01-15T10:29:59Z"
          },
          "customer_identifier": {
            "type": "string",
            "description": "End user identifier.",
            "example": "user_123"
          },
          "metadata": {
            "type": "object",
            "description": "Arbitrary key-value pairs.",
            "example": {
              "env": "production"
            }
          },
          "span_path": {
            "type": "string",
            "description": "Nested path within the workflow.",
            "example": "joke_creation.store_joke"
          },
          "encoding_format": {
            "type": "string",
            "description": "Embedding encoding format for embedding spans.",
            "example": "float"
          },
          "provider_id": {
            "type": "string",
            "description": "LLM or service provider ID.",
            "example": "openai"
          },
          "prompt_tokens": {
            "type": "integer",
            "description": "Number of prompt tokens used.",
            "example": 150
          },
          "completion_tokens": {
            "type": "integer",
            "description": "Number of completion tokens used.",
            "example": 80
          },
          "warnings": {
            "type": "string",
            "description": "Warnings captured during span execution."
          },
          "disable_log": {
            "type": "boolean",
            "description": "Set `true` to disable logging for this span.",
            "default": false
          },
          "respan_params": {
            "type": "object",
            "description": "Additional Respan parameters (e.g. `has_webhook`, `environment`)."
          },
          "temperature": {
            "type": "number",
            "description": "LLM temperature (0-2).",
            "example": 0.7
          },
          "presence_penalty": {
            "type": "number",
            "description": "Presence penalty for LLM requests.",
            "example": 0
          },
          "frequency_penalty": {
            "type": "number",
            "description": "Frequency penalty for LLM requests.",
            "example": 0
          },
          "max_tokens": {
            "type": "integer",
            "description": "Maximum tokens for completion.",
            "example": 1024
          },
          "stream": {
            "type": "boolean",
            "description": "Whether the response was streamed.",
            "default": false
          }
        }
      }
    },
    {
      "type": "object",
      "description": "Wrapper object accepted by the legacy integration endpoint.",
      "properties": {
        "data": {
          "type": "array",
          "description": "Array of span objects to ingest as traces.",
          "items": {
            "type": "object",
            "required": [
              "trace_unique_id",
              "span_unique_id"
            ],
            "properties": {
              "trace_unique_id": {
                "type": "string",
                "description": "Trace ID linking all spans.",
                "example": "trace_abc123"
              },
              "span_unique_id": {
                "type": "string",
                "description": "Unique ID for this span.",
                "example": "span_001"
              },
              "span_parent_id": {
                "type": "string",
                "nullable": true,
                "description": "Parent span ID. `null` for root spans.",
                "example": null
              },
              "span_name": {
                "type": "string",
                "description": "Name of this span.",
                "example": "llm_call"
              },
              "span_workflow_name": {
                "type": "string",
                "description": "Workflow name.",
                "example": "support_flow"
              },
              "log_type": {
                "type": "string",
                "description": "Span type.",
                "enum": [
                  "chat",
                  "completion",
                  "response",
                  "embedding",
                  "speech",
                  "transcription",
                  "workflow",
                  "agent",
                  "task",
                  "tool",
                  "guardrail",
                  "reranker",
                  "other"
                ],
                "default": "chat",
                "example": "chat"
              },
              "input": {
                "description": "Input to the model.",
                "example": "[{\"role\": \"user\", \"content\": \"Hello\"}]"
              },
              "output": {
                "description": "Output from the model.",
                "example": "{\"role\": \"assistant\", \"content\": \"Hi!\"}"
              },
              "model": {
                "type": "string",
                "description": "Model used.",
                "example": "gpt-4o"
              },
              "usage": {
                "type": "object",
                "description": "Token usage.",
                "example": {
                  "prompt_tokens": 10,
                  "completion_tokens": 8,
                  "total_tokens": 18
                }
              },
              "cost": {
                "type": "number",
                "description": "Cost in USD.",
                "example": 0.001
              },
              "latency": {
                "type": "number",
                "description": "Latency in seconds.",
                "example": 1.2
              },
              "status": {
                "type": "string",
                "enum": [
                  "success",
                  "error"
                ],
                "example": "success"
              },
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "description": "When completed (ISO 8601).",
                "example": "2025-01-15T10:30:00Z"
              },
              "start_time": {
                "type": "string",
                "format": "date-time",
                "description": "When started (ISO 8601).",
                "example": "2025-01-15T10:29:59Z"
              },
              "customer_identifier": {
                "type": "string",
                "description": "End user identifier.",
                "example": "user_123"
              },
              "metadata": {
                "type": "object",
                "description": "Arbitrary key-value pairs.",
                "example": {
                  "env": "production"
                }
              },
              "span_path": {
                "type": "string",
                "description": "Nested path within the workflow.",
                "example": "joke_creation.store_joke"
              },
              "encoding_format": {
                "type": "string",
                "description": "Embedding encoding format for embedding spans.",
                "example": "float"
              },
              "provider_id": {
                "type": "string",
                "description": "LLM or service provider ID.",
                "example": "openai"
              },
              "prompt_tokens": {
                "type": "integer",
                "description": "Number of prompt tokens used.",
                "example": 150
              },
              "completion_tokens": {
                "type": "integer",
                "description": "Number of completion tokens used.",
                "example": 80
              },
              "warnings": {
                "type": "string",
                "description": "Warnings captured during span execution."
              },
              "disable_log": {
                "type": "boolean",
                "description": "Set `true` to disable logging for this span.",
                "default": false
              },
              "respan_params": {
                "type": "object",
                "description": "Additional Respan parameters (e.g. `has_webhook`, `environment`)."
              },
              "temperature": {
                "type": "number",
                "description": "LLM temperature (0-2).",
                "example": 0.7
              },
              "presence_penalty": {
                "type": "number",
                "description": "Presence penalty for LLM requests.",
                "example": 0
              },
              "frequency_penalty": {
                "type": "number",
                "description": "Frequency penalty for LLM requests.",
                "example": 0
              },
              "max_tokens": {
                "type": "integer",
                "description": "Maximum tokens for completion.",
                "example": 1024
              },
              "stream": {
                "type": "boolean",
                "description": "Whether the response was streamed.",
                "default": false
              }
            }
          }
        }
      },
      "required": [
        "data"
      ]
    }
  ]
}

Responses

200

Trace spans processed successfully

application/json

Field Type Requirement Description and constraints
$ object Body
-
message string Required in parent
Human-readable ingest summary.
Example: "Processed 2 Vercel spans"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Human-readable ingest summary.",
      "example": "Processed 2 Vercel spans"
    }
  },
  "required": [
    "message"
  ]
}
Example
JSON
{ "message": "Processed 2 Vercel spans" }

400

Bad Request

application/json

Field Type Requirement Description and constraints
$ object Body
-
error string Required in parent
Example: "Invalid trace data format. Expected a list of spans or a dict with 'data' field containing a list."

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "example": "Invalid trace data format. Expected a list of spans or a dict with 'data' field containing a list."
    }
  },
  "required": [
    "error"
  ]
}

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
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

500

Internal Server Error

application/json

Field Type Requirement Description and constraints
$ object Body
-
error string Optional
Example: "Internal server error"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "example": "Internal server error"
    }
  }
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Ingest spans (legacy)",
  "operationId": "createTraceLegacy",
  "tags": [
    "Traces"
  ],
  "description": "Accepts spans as a JSON array or an object whose `data` field contains the array. Each span uses the fields in [Create a span](/docs/apis/spans/create-span), plus `trace_unique_id`, `span_unique_id`, and optional `span_parent_id` to build the trace tree. For new integrations, use [Ingest traces (OTLP)](/docs/apis/traces/ingest-traces-otlp).",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "oneOf": [
            {
              "type": "array",
              "description": "Array of span objects to ingest as traces.",
              "items": {
                "type": "object",
                "required": [
                  "trace_unique_id",
                  "span_unique_id"
                ],
                "properties": {
                  "trace_unique_id": {
                    "type": "string",
                    "description": "Trace ID linking all spans.",
                    "example": "trace_abc123"
                  },
                  "span_unique_id": {
                    "type": "string",
                    "description": "Unique ID for this span.",
                    "example": "span_001"
                  },
                  "span_parent_id": {
                    "type": "string",
                    "nullable": true,
                    "description": "Parent span ID. `null` for root spans.",
                    "example": null
                  },
                  "span_name": {
                    "type": "string",
                    "description": "Name of this span.",
                    "example": "llm_call"
                  },
                  "span_workflow_name": {
                    "type": "string",
                    "description": "Workflow name.",
                    "example": "support_flow"
                  },
                  "log_type": {
                    "type": "string",
                    "description": "Span type.",
                    "enum": [
                      "chat",
                      "completion",
                      "response",
                      "embedding",
                      "speech",
                      "transcription",
                      "workflow",
                      "agent",
                      "task",
                      "tool",
                      "guardrail",
                      "reranker",
                      "other"
                    ],
                    "default": "chat",
                    "example": "chat"
                  },
                  "input": {
                    "description": "Input to the model.",
                    "example": "[{\"role\": \"user\", \"content\": \"Hello\"}]"
                  },
                  "output": {
                    "description": "Output from the model.",
                    "example": "{\"role\": \"assistant\", \"content\": \"Hi!\"}"
                  },
                  "model": {
                    "type": "string",
                    "description": "Model used.",
                    "example": "gpt-4o"
                  },
                  "usage": {
                    "type": "object",
                    "description": "Token usage.",
                    "example": {
                      "prompt_tokens": 10,
                      "completion_tokens": 8,
                      "total_tokens": 18
                    }
                  },
                  "cost": {
                    "type": "number",
                    "description": "Cost in USD.",
                    "example": 0.001
                  },
                  "latency": {
                    "type": "number",
                    "description": "Latency in seconds.",
                    "example": 1.2
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "success",
                      "error"
                    ],
                    "example": "success"
                  },
                  "timestamp": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When completed (ISO 8601).",
                    "example": "2025-01-15T10:30:00Z"
                  },
                  "start_time": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When started (ISO 8601).",
                    "example": "2025-01-15T10:29:59Z"
                  },
                  "customer_identifier": {
                    "type": "string",
                    "description": "End user identifier.",
                    "example": "user_123"
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Arbitrary key-value pairs.",
                    "example": {
                      "env": "production"
                    }
                  },
                  "span_path": {
                    "type": "string",
                    "description": "Nested path within the workflow.",
                    "example": "joke_creation.store_joke"
                  },
                  "encoding_format": {
                    "type": "string",
                    "description": "Embedding encoding format for embedding spans.",
                    "example": "float"
                  },
                  "provider_id": {
                    "type": "string",
                    "description": "LLM or service provider ID.",
                    "example": "openai"
                  },
                  "prompt_tokens": {
                    "type": "integer",
                    "description": "Number of prompt tokens used.",
                    "example": 150
                  },
                  "completion_tokens": {
                    "type": "integer",
                    "description": "Number of completion tokens used.",
                    "example": 80
                  },
                  "warnings": {
                    "type": "string",
                    "description": "Warnings captured during span execution."
                  },
                  "disable_log": {
                    "type": "boolean",
                    "description": "Set `true` to disable logging for this span.",
                    "default": false
                  },
                  "respan_params": {
                    "type": "object",
                    "description": "Additional Respan parameters (e.g. `has_webhook`, `environment`)."
                  },
                  "temperature": {
                    "type": "number",
                    "description": "LLM temperature (0-2).",
                    "example": 0.7
                  },
                  "presence_penalty": {
                    "type": "number",
                    "description": "Presence penalty for LLM requests.",
                    "example": 0
                  },
                  "frequency_penalty": {
                    "type": "number",
                    "description": "Frequency penalty for LLM requests.",
                    "example": 0
                  },
                  "max_tokens": {
                    "type": "integer",
                    "description": "Maximum tokens for completion.",
                    "example": 1024
                  },
                  "stream": {
                    "type": "boolean",
                    "description": "Whether the response was streamed.",
                    "default": false
                  }
                }
              }
            },
            {
              "type": "object",
              "description": "Wrapper object accepted by the legacy integration endpoint.",
              "properties": {
                "data": {
                  "type": "array",
                  "description": "Array of span objects to ingest as traces.",
                  "items": {
                    "type": "object",
                    "required": [
                      "trace_unique_id",
                      "span_unique_id"
                    ],
                    "properties": {
                      "trace_unique_id": {
                        "type": "string",
                        "description": "Trace ID linking all spans.",
                        "example": "trace_abc123"
                      },
                      "span_unique_id": {
                        "type": "string",
                        "description": "Unique ID for this span.",
                        "example": "span_001"
                      },
                      "span_parent_id": {
                        "type": "string",
                        "nullable": true,
                        "description": "Parent span ID. `null` for root spans.",
                        "example": null
                      },
                      "span_name": {
                        "type": "string",
                        "description": "Name of this span.",
                        "example": "llm_call"
                      },
                      "span_workflow_name": {
                        "type": "string",
                        "description": "Workflow name.",
                        "example": "support_flow"
                      },
                      "log_type": {
                        "type": "string",
                        "description": "Span type.",
                        "enum": [
                          "chat",
                          "completion",
                          "response",
                          "embedding",
                          "speech",
                          "transcription",
                          "workflow",
                          "agent",
                          "task",
                          "tool",
                          "guardrail",
                          "reranker",
                          "other"
                        ],
                        "default": "chat",
                        "example": "chat"
                      },
                      "input": {
                        "description": "Input to the model.",
                        "example": "[{\"role\": \"user\", \"content\": \"Hello\"}]"
                      },
                      "output": {
                        "description": "Output from the model.",
                        "example": "{\"role\": \"assistant\", \"content\": \"Hi!\"}"
                      },
                      "model": {
                        "type": "string",
                        "description": "Model used.",
                        "example": "gpt-4o"
                      },
                      "usage": {
                        "type": "object",
                        "description": "Token usage.",
                        "example": {
                          "prompt_tokens": 10,
                          "completion_tokens": 8,
                          "total_tokens": 18
                        }
                      },
                      "cost": {
                        "type": "number",
                        "description": "Cost in USD.",
                        "example": 0.001
                      },
                      "latency": {
                        "type": "number",
                        "description": "Latency in seconds.",
                        "example": 1.2
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "success",
                          "error"
                        ],
                        "example": "success"
                      },
                      "timestamp": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When completed (ISO 8601).",
                        "example": "2025-01-15T10:30:00Z"
                      },
                      "start_time": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When started (ISO 8601).",
                        "example": "2025-01-15T10:29:59Z"
                      },
                      "customer_identifier": {
                        "type": "string",
                        "description": "End user identifier.",
                        "example": "user_123"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "Arbitrary key-value pairs.",
                        "example": {
                          "env": "production"
                        }
                      },
                      "span_path": {
                        "type": "string",
                        "description": "Nested path within the workflow.",
                        "example": "joke_creation.store_joke"
                      },
                      "encoding_format": {
                        "type": "string",
                        "description": "Embedding encoding format for embedding spans.",
                        "example": "float"
                      },
                      "provider_id": {
                        "type": "string",
                        "description": "LLM or service provider ID.",
                        "example": "openai"
                      },
                      "prompt_tokens": {
                        "type": "integer",
                        "description": "Number of prompt tokens used.",
                        "example": 150
                      },
                      "completion_tokens": {
                        "type": "integer",
                        "description": "Number of completion tokens used.",
                        "example": 80
                      },
                      "warnings": {
                        "type": "string",
                        "description": "Warnings captured during span execution."
                      },
                      "disable_log": {
                        "type": "boolean",
                        "description": "Set `true` to disable logging for this span.",
                        "default": false
                      },
                      "respan_params": {
                        "type": "object",
                        "description": "Additional Respan parameters (e.g. `has_webhook`, `environment`)."
                      },
                      "temperature": {
                        "type": "number",
                        "description": "LLM temperature (0-2).",
                        "example": 0.7
                      },
                      "presence_penalty": {
                        "type": "number",
                        "description": "Presence penalty for LLM requests.",
                        "example": 0
                      },
                      "frequency_penalty": {
                        "type": "number",
                        "description": "Frequency penalty for LLM requests.",
                        "example": 0
                      },
                      "max_tokens": {
                        "type": "integer",
                        "description": "Maximum tokens for completion.",
                        "example": 1024
                      },
                      "stream": {
                        "type": "boolean",
                        "description": "Whether the response was streamed.",
                        "default": false
                      }
                    }
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Trace spans processed successfully",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "description": "Human-readable ingest summary.",
                "example": "Processed 2 Vercel spans"
              }
            },
            "required": [
              "message"
            ]
          },
          "example": {
            "message": "Processed 2 Vercel spans"
          }
        }
      }
    },
    "400": {
      "description": "Bad Request",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "example": "Invalid trace data format. Expected a list of spans or a dict with 'data' field containing a list."
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "500": {
      "description": "Internal Server Error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "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."
          }
        }
      }
    }
  },
  "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"
      }
    }
  }
}