Sign in
Deprecated

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"
      }
    }
  ]
}
post/tracing/spans/ingest

Request body

tracesobject 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

Successful Response

countinteger

Number of spans that were accepted and published to the ingest stream. Compare against the number of spans you sent to detect partial failures.

Changes

Changed in 11 of the 378 revisions of this API.6332

  • fc532d6dc8209See the full diff
    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new optional request property ///////

      new-optional-request-property

    • ○

      added the new optional request property ///////

      new-optional-request-property

    • ○

      added the new optional request property ///////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    This revision also has 15 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • a7f9a68232302See the full diff
    • ●

      removed the optional property from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property from the response with the status

      response-optional-property-removed

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • d7e21f629c881See the full diff
    • ●

      removed the optional property from the response with the status

      response-optional-property-removed

  • bb630edffa273See the full diff
    • ○

      api tag Deprecated added

      api-tag-added

    • ○

      api tag Traces removed

      api-tag-removed

    • ○

      endpoint deprecated

      endpoint-deprecated

  • 5e6f53ce5d081See the full diff
    • ○

      api operation id ingest_spans_rpc removed and replaced with ingest_spans

      api-operation-id-removed

    This revision also has 64 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 6e37373d45fe2See the full diff
    • ○

      api tag Traces added

      api-tag-added

    • ○

      api tag Observability removed

      api-tag-removed

    This revision also has 11 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 925e8b901a263See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 20311f763505610See the full diff
    • ▲

      removed from the ///// request property anyOf list

      request-property-any-of-removed

    • ▲

      removed from the ////////// request property anyOf list

      request-property-any-of-removed

    • ▲

      the response property /// became optional for the status

      response-property-became-optional

    • ▲

      the response property /// became optional for the status

      response-property-became-optional

    • ▲

      response property links/anyOf[subschema #1]/items/span_id list-of-types was widened by adding types null to media type application/json of response 202

      response-property-list-of-types-widened

    • ▲

      response property links/anyOf[subschema #1]/items/trace_id list-of-types was widened by adding types null to media type application/json of response 202

      response-property-list-of-types-widened

    • ○

      added to the ///// request property anyOf list

      request-property-any-of-added

    • ○

      added to the ////////// request property anyOf list

      request-property-any-of-added

    • ○

      the request property ////// became optional

      request-property-became-optional

    • ○

      the request property ////// became optional

      request-property-became-optional

    • ○

      the request property /////////// became optional

      request-property-became-optional

    • ○

      the request property /////////// became optional

      request-property-became-optional

    • ○

      request property ////// list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property ////// list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property /////////// list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property /////////// list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 72fe88316d152See the full diff
    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    This revision also has 31 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 53da4c9de2b71See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 56 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog