---
title: "Ingest Spans"
method: POST
path: "/tracing/spans/ingest"
tags: ["Deprecated"]
deprecated: true
---

# Ingest Spans

`POST /tracing/spans/ingest`

> **Deprecated.**

Ingest spans into the tracing backend.

Use this endpoint to write full OpenTelemetry-style spans — including
multi-span hierarchies (parent → child → grandchild), attributes,
references, events and links. For simple single-span annotations or
evaluator outputs, prefer `POST /preview/tracing/traces/`
(`create_simple_trace`) — it's a higher-level helper on top of this
endpoint.

## Request body

Provide exactly one of:

- `spans`: a flat list of spans. Parent/child relationships are
  expressed via `parent_id` on each span.
- `traces`: a nested tree keyed by `trace_id` then by span name,
  where each node may contain a `spans` dict of its children. The
  query endpoint (`POST /tracing/spans/query`) returns this shape.

Each span requires `trace_id`, `span_id`, `start_time`, `end_time`.
`trace_id` must be a 32-char hex UUID, `span_id` a 16-char hex.
Attributes follow the Agenta convention under the `ag` namespace
(`ag.type`, `ag.data`, `ag.metrics`, `ag.references`) and may be
submitted either as a flat dotted map (OTel wire format) or as a
nested object — both are accepted.

## Response

Returns `202 Accepted` with the links (`trace_id` + `span_id`) for
the spans that were parsed into the ingest stream. See
[Tracing — Async write
contract](/reference/api-guide/tracing#async-write-contract-202)
for what `count < N submitted` means.

## Example

```json
{
  "spans": [
    {
      "trace_id": "f5a2efb40895881e938e2ebc070beca8",
      "span_id": "15f3df0731995245",
      "span_name": "completion_v0",
      "span_type": "workflow",
      "span_kind": "SPAN_KIND_SERVER",
      "start_time": "2026-04-16T18:18:18.491929Z",
      "end_time": "2026-04-16T18:18:20.415372Z",
      "attributes": {
        "ag.type.trace": "invocation",
        "ag.type.span": "workflow",
        "ag.data.inputs.country": "France",
        "ag.data.outputs": "Paris"
      }
    }
  ]
}
```

## Request body

- OTelTracingRequest — Ingest or query payload for OpenTelemetry-style spans. Exactly one of `spans` or `traces` should be provided. Use `spans` for a flat list (parent/child linked via `parent_id`); use `traces` for a nested tree (keyed by `trace_id` then by span name, children hanging off each node's `spans` field). The two shapes are interchangeable and the query endpoint returns the `traces` shape by default. See [Tracing](/reference/api-guide/tracing) for the full attribute namespace and the async ingest contract.
  - `spans` SpanInput[], nullable — Flat list of spans. Use this when you already have a flat list and parent/child relationships are expressed via each span's `parent_id`.
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
    - `deleted_at` string, date-time, nullable
    - `created_by_id` string, uuid, nullable
    - `updated_by_id` string, uuid, nullable
    - `deleted_by_id` string, uuid, nullable
    - `trace_id` string, required
    - `span_id` string, required
    - `parent_id` string, nullable
    - `trace_type` 'invocation' | 'annotation' | 'unknown'
    - `span_type` 'agent' | 'chain' | 'workflow' | 'task' | 'tool' | 'embedding' | 'query' | 'llm' | 'completion' | 'chat' | 'rerank' | 'unknown'
    - `span_kind` 'SPAN_KIND_UNSPECIFIED' | 'SPAN_KIND_INTERNAL' | 'SPAN_KIND_SERVER' | 'SPAN_KIND_CLIENT' | 'SPAN_KIND_PRODUCER' | 'SPAN_KIND_CONSUMER'
    - `span_name` string, nullable
    - `start_time` union
      - string, date-time
      - integer
    - `end_time` union
      - string, date-time
      - integer
    - `status_code` 'STATUS_CODE_UNSET' | 'STATUS_CODE_OK' | 'STATUS_CODE_ERROR'
    - `status_message` string, nullable
    - `session_id` string, nullable
    - `user_id` string, nullable
    - `agent_id` string, nullable
    - `attributes` object, nullable
    - `references` OTelReferenceInput[], nullable
      - `version` string, nullable
      - `slug` string, nullable
      - `id` string, uuid, nullable
      - `attributes` object, nullable
    - `links` OTelLinkInput[], nullable
      - `span_id` string, nullable
      - `trace_id` string, nullable
      - `attributes` object, nullable
    - `hashes` OTelHashInput[], nullable
      - `id` string, uuid, nullable
      - `attributes` object, nullable
    - `exception` object, nullable
    - `events` OTelEventInput[], nullable
      - `name` string, required
      - `timestamp` union, required
        - string, date-time
        - integer
      - `attributes` object, nullable
  - `traces` object, nullable — Nested tree of spans keyed by `trace_id` → span name, with children under each node's `spans` field. This matches the shape returned by `POST /tracing/spans/query` with `focus="trace"`.

## Response `202`

Successful Response

- OTelLinksResponse — Response from span ingestion. `count` reflects how many spans were successfully parsed and published to the ingest stream. If you submitted N spans and see `count < N`, some spans failed server-side validation and were not persisted (check server logs for details). See [Tracing — Async write contract](/reference/api-guide/tracing#async-write-contract-202) for the full semantics of the `202 Accepted` response.
  - `count` integer — Number of spans that were accepted and published to the ingest stream. Compare against the number of spans you sent to detect partial failures.
  - `links` OTelLinkOutput[], nullable — List of `(trace_id, span_id)` pairs for the accepted spans, in submission order.
    - `span_id` string, nullable
    - `trace_id` string, nullable
    - `attributes` object, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agenta-ai/apis/agenta-api.md) · [All operations](https://skmtc.net/agenta-ai/apis/agenta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agenta-ai/agenta-api/versions/2e1079696f45/schema)