Move `tracing` away from deprecated (and then legacy) endpoints.

[junaway]

Tracing API — Legacy Endpoints & Migration Guide

1. Legacy endpoints currently used by the web

All web calls go through /tracing/* (deprecated) or /tracing/spans/analytics (legacy, not formally deprecated).

Endpoint	Status	Web callers
POST /tracing/spans/query	Deprecated	fetchAllPreviewTraces(), fetchAllPreviewTracesWithMeta() in web/oss/src/services/tracing/api/index.ts and web/packages/agenta-entities/src/trace/api/api.ts
POST /tracing/spans/analytics	Legacy (not deprecated)	fetchGenerationsDashboardData() in web/oss/src/services/tracing/api/index.ts
GET /tracing/traces/{id}	Deprecated	fetchPreviewTrace() in both files above
DELETE /tracing/traces/{id}	Deprecated	deletePreviewTrace() in both files above
POST /tracing/sessions/query	Deprecated	fetchSessions() in both files above

Deprecated endpoints that web does not call (safe to ignore for web migration):
POST /tracing/spans/ingest, POST /tracing/analytics/query, POST /tracing/traces/, PUT /tracing/traces/{id}, POST /tracing/users/query.

---

2. Migration considerations per endpoint

2.1 POST /tracing/spans/query → POST /spans/query

Request — what changes:

Field	Legacy	New
Pagination	windowing.limit, windowing.oldest/newest (implicit)	windowing object — same struct, but cursor-only; oldest/newest as datetime
Filtering	filter as freeform JSON blob	filtering as structured {operator, conditions[]}
Focus	focus: "trace" | "span" | "chat" in body	focus removed — new endpoint always returns flat spans; query revisions with focus="trace" return 409
Format	format: "agenta" | "openai" | ...	formatting object with {focus, format}
Saved query	query_ref / query_variant_ref / query_revision_ref	Same — unchanged

Response — what changes:

	Legacy OTelTracingResponse	New SpansResponse
Shape	{count, spans?, traces?} — one or the other depending on focus	{count, spans} — always flat list, never traces
Trace-tree view	Available via focus="trace"	Not available — use GET /traces/ instead

Impact: The web currently relies on focus="trace" to get the trace-tree shape. The new endpoint drops this entirely. The web would need to either: (a) keep using /tracing/spans/query until a proper trace-tree endpoint migration is scoped, or (b) switch to GET /traces/ for trace-tree views and POST /spans/query for flat span views separately.

---

2.2 POST /tracing/spans/analytics → POST /spans/analytics/query

Request — what changes:

Field	Legacy	New
Interval	interval: str (seconds as string)	Same
Filtering	filter blob	filtering structured object
Metrics	Implicit — fixed schema	specs: List[MetricSpec] — user-defined

Response — what changes:

	Legacy OldAnalyticsResponse	New AnalyticsResponse
Buckets	{total: {count, duration, costs, tokens}, errors: {...}} — hardcoded fields	{metrics: Dict[str, any]} keyed by spec.path — user-defined
Query echo	Not returned	query and specs echoed back

Impact: The web's fetchGenerationsDashboardData is tightly coupled to the fixed bucket schema (total.count, errors.count, etc.). Migration requires changing both the request (add specs) and the response parsing.

---

2.3 GET /tracing/traces/{id} → GET /traces/{id}

Request: No change (path param only).

Response — what changes:

	Legacy OTelTracingResponse	New TraceResponse
Shape	{count, traces: {[traceId]: {spans: {...}}}} — map keyed by trace_id	{count, trace: {trace_id, spans: [...]}} — single object
Key	traces (plural, record)	trace (singular, object)
Spans	Nested dict by span name	Flat list or tree

Impact: The frontend tracesResponseSchema expects the legacy traces record shape. Migrating requires updating the Zod schema and all consumers of fetchPreviewTrace.

---

2.4 DELETE /tracing/traces/{id} → DELETE /traces/{id}

Request: No change (path param only).

Response — what changes:

	Legacy OTelLinksResponse	New TraceIdResponse
Shape	{count, links: [{trace_id, span_id}]} — list of deleted span links	{count, trace_id} — just the deleted trace_id

Impact: Low — the web currently ignores the delete response body.

---

2.5 POST /tracing/sessions/query → POST /spans/sessions/query

Request: No change — same {realtime?, windowing?} shape.

Response: No change — same {count, session_ids, windowing} shape.

Impact: URL-only change, no schema migration needed.

---

2.6 Sessions / Users — no web callers for users

POST /tracing/users/query has no web callers. Its replacement POST /spans/users/query is identical in request/response. Migration is a URL swap if/when needed.

[linear-code]

AGE-3788

[junaway]

@ardaerzin
POST /tracing/spans/analytics would probably be last, as a separate effort, later in the future.