Traces

Create Trace

Changed on

Create a single-span "simple" trace.

This endpoint is a higher-level helper for the common case of recording one self-contained event — an evaluator output, a human annotation, a feedback entry, a manually-logged inference. It creates one span under a fresh trace_id and returns the resulting handle.

When to use this vs. /tracing/spans/ingest

  • Use this endpoint when you have a single payload to record with no internal hierarchy: evaluation results, human feedback, manual annotations, or a standalone completion. It takes care of trace_id/span_id generation, attribute namespacing, and link wiring for you.
  • Use POST /tracing/spans/ingest when you need multi-span traces (e.g. an agent run with nested tool calls and LLM spans), precise control over IDs, timings, or parent/child relationships, or when forwarding traces from another OTel-compatible source.

Request body

Send a trace object with:

  • origin — who produced the trace (human, auto, custom).
  • kind — intent (adhoc, eval, play).
  • channel — transport that produced it (sdk, api, web, otlp).
  • data — required dict carrying the actual payload (inputs, outputs, or evaluator results).
  • tags, meta — optional free-form dicts for filtering and metadata.
  • references — optional links to Agenta entities (application, variant, revision, evaluator, testset, etc.).
  • links — optional OTel-style links to other traces/spans.

Use PATCH /preview/tracing/traces/{trace_id} to update fields later, GET to fetch, and DELETE to remove. See Tracing — References and links for when to use references vs. links.

post/simple/traces/

Request

  • Base URL
    /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL
    /api/simple/traces/
  • Auth
    API key in header Authorization

Request body

Response

Successful Response

countinteger

1 if the trace was returned, 0 otherwise.

Changes

  • b2f21936417eRevision changes
    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

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

    • info

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

    • info

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

    • info

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

  • c26abd89e092Revision changes
    • warning

      removed the request property //

    • warning

      removed the request property //

    • warning

      removed the request property //

    • warning

      removed the request property //

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status