Ingest Spans

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 for what count < N submitted means.

Example

{
  "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"
      }
    }
  ]
}