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

# Ingest spans from traces (v1 legacy)

`POST /api/v1/traces/ingest`

Legacy trace-ingest endpoint. Accepts spans either as a raw JSON array or as an object with a `data` field containing the span array. Each span uses the same fields as [Create a span](/docs/apis/spans/api-request-logs), plus `trace_unique_id`, `span_unique_id`, and optional `span_parent_id` to build the trace tree. For new integrations, prefer [Create a trace (OTLP)](/docs/apis/traces/create-trace).

## Headers

- `Authorization` string, required

## Request body

- union
  - ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf0Items[] — 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` unknown
    - `output` unknown
    - `model` string — Model used.
    - `usage` ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf0ItemsUsage — Token usage.
    - `cost` number, double — Cost in USD.
    - `latency` number, double — 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` ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf0ItemsMetadata — 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` ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf0ItemsRespanParams — Additional Respan parameters (e.g. `has_webhook`, `environment`).
    - `temperature` number, double — LLM temperature (0-2).
    - `presence_penalty` number, double — Presence penalty for LLM requests.
    - `frequency_penalty` number, double — Frequency penalty for LLM requests.
    - `max_tokens` integer — Maximum tokens for completion.
    - `stream` boolean — Whether the response was streamed.
  - TracesCreateTraceLegacyRequest1 — Wrapper object accepted by the legacy integration endpoint.
    - `data` ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItems[], 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` unknown
      - `output` unknown
      - `model` string — Model used.
      - `usage` ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsUsage — Token usage.
      - `cost` number, double — Cost in USD.
      - `latency` number, double — 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` ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsMetadata — 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` ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsRespanParams — Additional Respan parameters (e.g. `has_webhook`, `environment`).
      - `temperature` number, double — LLM temperature (0-2).
      - `presence_penalty` number, double — Presence penalty for LLM requests.
      - `frequency_penalty` number, double — 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

- TracesCreateTraceLegacyResponse200
  - `message` string, required — Human-readable ingest summary.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized - Missing/invalid authentication
- `500` — Internal Server Error

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)