Skip to main content
Version: v2.0

Query Spans

POST 
/tracing/spans/query
deprecated

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

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.

Request​

Responses​

Successful Response