Pagination Issue - api/v3/traces endpoint

[ramanamark-virtana]

I believe there's no cursor/offset-based pagination in v3 yet, Could you please let us know whether this will be developed as a feature or this will be discarded?

[0xshubhs]

Your read is correct, and it's being developed — not discarded.

Today: there is no offset, cursor, or continuation token anywhere in api_v3, the internal tracestore.Reader interface, or the Remote Storage gRPC protocol. search_depth (field 8, default 100) is a cap, not a page size — raising it just fetches a bigger first page. The Offset int field on the v1 HTTP query struct is parsed and then never read by any query path; it's dead code, not a hidden way in.

Planned: RFC 0014 — Search Result Pagination, authored by Yuri Shkuro, created 2026-08-12, currently Draft. It adds end-to-end keyset pagination: an opaque page_token on the request, next_page_token on the response, threaded through all three layers, plus a storage capability declaration so a backend that can't paginate degrades to one capped page instead of silently returning partial results. It's explicitly additive — search_depth keeps working and clients that send no token see today's behavior.

One thing the RFC flags that's worth knowing regardless of pagination: on ES/OpenSearch, FindTraceIDs uses a terms aggregation on traceID ordered by a max(startTime) sub-aggregation, which is only approximate across shards, and shard_size isn't set to widen the candidate set. So the current single page isn't reliably "the N most recent traces" either. Fixing that ordering is a prerequisite in the RFC, which is why this is a larger job than bolting on a cursor.

Note offset paging was considered and rejected — §10 covers why, and recommends deleting the dead Offset field.

Your #9369 is the tracking issue; RFC 0014 is where the design discussion is happening.

[ramanamark-virtana]

Thanks for your clarification.