Skip to main content

Ingest Spans

POST 
/tracing/spans/ingest
deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

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

Request​

Responses​

Successful Response