---
title: "Ingest spans (legacy)"
method: POST
path: "/api/v1/traces/ingest"
tags: ["Traces"]
---

# Ingest spans (legacy)

`POST /api/v1/traces/ingest`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/v1/traces/ingest`
- Auth: HTTP bearer

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).

## Request body

- union
  - object[]: Array of span objects to ingest as traces.
    - `trace_unique_id` string, required: Trace ID linking all spans.
    - `span_unique_id` string, required: Unique ID for this span.
    - `span_parent_id` string, nullable: Parent span ID. `null` for root spans.
    - `span_name` string: Name of this span.
    - `span_workflow_name` string: Workflow name.
    - `log_type` 'chat' | 'completion' | 'response' | 'embedding' | 'speech' | 'transcription' | 'workflow' | 'agent' | 'task' | 'tool' | 'guardrail' | 'reranker' | 'other': Span type.
    - `input` string: Input to the model.
    - `output` string: Output from the model.
    - `model` string: Model used.
    - `usage` object: Token usage.
    - `cost` number: Cost in USD.
    - `latency` number: Latency in seconds.
    - `status` 'success' | 'error'
    - `timestamp` string, date-time: When completed (ISO 8601).
    - `start_time` string, date-time: When started (ISO 8601).
    - `customer_identifier` string: End user identifier.
    - `metadata` object: Arbitrary key-value pairs.
    - `span_path` string: Nested path within the workflow.
    - `encoding_format` string: Embedding encoding format for embedding spans.
    - `provider_id` string: LLM or service provider ID.
    - `prompt_tokens` integer: Number of prompt tokens used.
    - `completion_tokens` integer: Number of completion tokens used.
    - `warnings` string: Warnings captured during span execution.
    - `disable_log` boolean: Set `true` to disable logging for this span.
    - `disable_fallback` boolean: Disable fallback behavior for this span.
    - `respan_params` object: Additional Respan parameters (e.g. `has_webhook`, `environment`).
    - `temperature` number: LLM temperature (0-2).
    - `presence_penalty` number: Presence penalty for LLM requests.
    - `frequency_penalty` number: Frequency penalty for LLM requests.
    - `max_tokens` integer: Maximum tokens for completion.
    - `stream` boolean: Whether the response was streamed.
  - object: Wrapper object accepted by the legacy integration endpoint.
    - `data` object[], required: Array of span objects to ingest as traces.
      - `trace_unique_id` string, required: Trace ID linking all spans.
      - `span_unique_id` string, required: Unique ID for this span.
      - `span_parent_id` string, nullable: Parent span ID. `null` for root spans.
      - `span_name` string: Name of this span.
      - `span_workflow_name` string: Workflow name.
      - `log_type` 'chat' | 'completion' | 'response' | 'embedding' | 'speech' | 'transcription' | 'workflow' | 'agent' | 'task' | 'tool' | 'guardrail' | 'reranker' | 'other': Span type.
      - `input` string: Input to the model.
      - `output` string: Output from the model.
      - `model` string: Model used.
      - `usage` object: Token usage.
      - `cost` number: Cost in USD.
      - `latency` number: Latency in seconds.
      - `status` 'success' | 'error'
      - `timestamp` string, date-time: When completed (ISO 8601).
      - `start_time` string, date-time: When started (ISO 8601).
      - `customer_identifier` string: End user identifier.
      - `metadata` object: Arbitrary key-value pairs.
      - `span_path` string: Nested path within the workflow.
      - `encoding_format` string: Embedding encoding format for embedding spans.
      - `provider_id` string: LLM or service provider ID.
      - `prompt_tokens` integer: Number of prompt tokens used.
      - `completion_tokens` integer: Number of completion tokens used.
      - `warnings` string: Warnings captured during span execution.
      - `disable_log` boolean: Set `true` to disable logging for this span.
      - `disable_fallback` boolean: Disable fallback behavior for this span.
      - `respan_params` object: Additional Respan parameters (e.g. `has_webhook`, `environment`).
      - `temperature` number: LLM temperature (0-2).
      - `presence_penalty` number: Presence penalty for LLM requests.
      - `frequency_penalty` number: Frequency penalty for LLM requests.
      - `max_tokens` integer: Maximum tokens for completion.
      - `stream` boolean: Whether the response was streamed.

## Response `200`

Trace spans processed successfully

- object
  - `message` string, required: Human-readable ingest summary.

## Other responses

- `400`: Bad Request
- `403`: The API key is missing, invalid or expired.
- `500`: Internal Server Error

## Changes

- **2026-10-21** `c30bcb383ee8`: 2 breaking, 4 info
  - request body became required
  - removed `#/components/schemas/TracesCreateTraceLegacyRequest0, #/components/schemas/TracesCreateTraceLegacyRequest1` from the request body `oneOf` list
  - api operation id `traces_createTraceLegacy` removed and replaced with `createTraceLegacy`
  - api tag `Traces` added
  - …2 more
- **2026-10-02** `b830b79cfd52`: 2 info
  - added the non-success response with the status `403`
  - removed the non-success response with the status `401`
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `create-trace-legacy` removed and replaced with `traces_createTraceLegacy`
- **2026-08-13** `4e064cf81dae`: 5 info
  - added optional request body
  - added the non-success response with the status `400`
  - added the non-success response with the status `401`
  - added the non-success response with the status `500`
  - …1 more

[Operation history](https://skmtc.dev/keywordsai/apis/respan-api/changes/api/v1/traces/ingest/post.md)

---

[API](https://skmtc.dev/keywordsai/apis/respan-api.md) - [All operations](https://skmtc.dev/keywordsai/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keywordsai/apis/respan-api/revisions/900841387635?raw)