Query sessions
Returns a paginated list of sessions with aggregated metrics, one row per distinct session ID in the requested time range.
The preferred alternative to POST /v3/fetch-sessions, which returns bare session ID strings with no metadata and requires a follow-up call per session to render anything useful. fetch-sessions is not deprecated by this endpoint’s introduction; a deprecation is a separate decision with its own migration path.
Time range is required, including when session_ids is supplied. Sessions are aggregated across their spans, so without a bounded window the query cannot prune partitions and would group the entire trace table. This differs from the other session-addressed endpoints — DELETE /v3/sessions and GET /v3/sessions/{session_id}/timeline both take IDs with no window — because neither of those can be asked to aggregate an unbounded set of spans, and partition pruning is this endpoint’s only hard bound on query cost.
Metrics are computed over the requested window, not the session’s whole lifetime. See the Session schema.
Filters are explicit typed fields, not the QueryCondition DSL used by POST /v3/spans/query. The only optional filter at launch is session_ids. Expressing a simple ID list as a DSL tree is strictly worse ergonomics for no functional gain; a filter field can be added later without breaking this contract.
Sorting is restricted to start_time. Sorting by aggregates (duration, span_count, total_tokens) is not yet supported and is rejected with a 400.
status and full-text search are deliberately absent. A session-level status means imposing a severity order on OTel StatusCode, and the ambiguous case is the common one: a session whose spans are all Unset. Redefining a response field later is a breaking change, whereas adding one is not, so this waits for a decision rather than shipping a guess. search is a different query shape at session granularity than at span granularity — matching is per span, but the aggregates must still cover every span of a matched session, not only the matching ones. Both can be added later without breaking this contract.
Spans carrying no session ID are excluded. Sessions are scoped to a single application.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Request body for POST /v3/sessions/query. Unknown fields are rejected with a 400.
UUID of the Fiddler GenAI application.
"c688de46-2054-49ab-b85f-0f0178cb44d7"
Start of the time range (inclusive, UTC). Must be timezone-aware and strictly before end_time. Matched against span start timestamps, so a session that began before this bound appears only if it also has spans inside the window.
"2026-03-01T00:00:00Z"
End of the time range (exclusive, UTC). Must be timezone-aware.
"2026-03-02T00:00:00Z"
Optional allow-list of session IDs. Omit or pass null to return all sessions in the window. An empty array is treated as omitted. Empty-string entries are rejected — spans with no session context are excluded from this endpoint, so "" can never match. The cap matches DELETE /v3/sessions, so the same ID list works against either endpoint; a list longer than page_size simply spans several pages.
1000Session ID grouping related traces
1Sort field with an optional leading - for descending. Only start_time is supported; any other field is rejected with a 400.
start_time, -start_time Number of sessions per page.
1 <= x <= 20050
Zero-based offset into the result set. Deep pagination re-scans the window through a GROUP BY, so the offset is capped. Because of this cap, data.page_count in the response can advertise pages beyond what this endpoint will actually serve: page_count is ceil(total / page_size) with no awareness of the offset limit, so a large total with a small page_size can put the last page's offset past 10000. Requesting such a page returns 400, not an empty result. A client walking pages by index should stop once its next offset would exceed 10000, not once it reaches page_count.
0 <= x <= 100000
Response
A paginated list of sessions matching the query