Query Spans

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.

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.