Deprecated

Query Spans

Changed on

Query spans and traces in the tracing backend.

Use focus in the request body to control the response shape:

  • "trace" (default): returns a nested traces tree keyed by trace_id then by span name. Children hang off their parent's spans field. Best for rendering a trace waterfall.
  • "span": returns a flat spans list. Best for paginating or filtering across all spans regardless of hierarchy.

Use oldest / newest (unix seconds) to window the query and limit to cap the number of traces/spans returned. One response holds at most one page: 100 rows when limit is not set, and never more than 1000 (the server settings AGENTA_API_TRACING_QUERY_DEFAULT_LIMIT and AGENTA_API_TRACING_QUERY_MAX_LIMIT). When the page is full, the response has a windowing object: send it as windowing to read the next page.

Span attributes here leave out ag.data.parameters.agent.skills (the skill text of an agent run). To read a whole trace, filter only on trace_id, or call GET /traces/{trace_id}.

The response preserves the Agenta ag.* attribute namespace and includes computed metrics (ag.metrics.duration, ag.metrics.tokens, ag.metrics.costs) on each span. The traces tree returned here is the same shape that POST /tracing/spans/ingest accepts as its traces field.

post/tracing/spans/query

Request

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

Query parameters

focus'trace' | 'span'
format'agenta' | 'opentelemetry'
string
OR
integer
string
OR
integer
limitinteger nullable
intervalinteger nullable
ratenumber nullable
filterunknown

Response

Successful Response

countinteger

Total number of matching traces or spans in the window.

tracesobject nullable

Nested tree of spans keyed by trace_id → span name, populated when the query was run with focus="trace" (default).

Changes

  • 4935907204a4Revision changes
    • info

      added the optional property to the response with the status

  • fc532d6dc820Revision changes
    • 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

    • 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

    • info

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