Query traces as a list of canonical Trace records.

Thin wrapper over the shared span-query backend that forces focus = "trace" and returns the list-shaped Traces payload (one entry per trace, each with its nested spans tree). Use this to build a table of runs, where each row is a trace.

Request body

• filtering — span-level conditions, same dialect as POST /spans/query. A trace matches when any of its spans matches.
• windowing — cursor pagination and time range.
• query_ref, query_variant_ref, query_revision_ref — resolve filters and windowing from a saved query revision. If the revision's stored formatting.focus is span, this endpoint returns 409 — call POST /spans/query instead.

Response

Returns {count, traces: [...], windowing}. One response holds at most one page: 100 traces when windowing.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). windowing is present when the page is full: send it as windowing to read the next page. A trace with matching spans on both sides of a page boundary can appear on both pages; deduplicate by trace_id. A query that filters only on trace_id returns those traces whole, with no limit.

Span attributes leave out ag.data.parameters.agent.skills (the skill text of an agent run), except when the query filters only on trace_id. GET /traces/{trace_id} returns it too.

For the per-trace map shape keyed by trace_id, call POST /tracing/spans/query with focus="trace".