@mastra/client-js 1.56.0-alpha.7 → 1.56.0-alpha.9

package/dist/client.d.ts

@@ -52,7 +52,7 @@ export declare class MastraClient extends BaseResource {
     listAgentControllers(): Promise<AgentControllerInfo[]>;
     /**
      * Scopes to an agent controller hosted on the connected Mastra instance. Use
-     * `getAgentController(id).session(resourceId)` to create/resume a session,
+     * `getAgentController(id).session(sessionId)` to create/resume a session,
      * stream its events, and send messages.
      * @param controllerId - The id the agent controller is registered under on Mastra
      */

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-client-js
 description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
 metadata:
   package: "@mastra/client-js"
-  version: "1.56.0-alpha.7"
+  version: "1.56.0-alpha.9"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.56.0-alpha.7",
+  "version": "1.56.0-alpha.9",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-harness-agent-controller.md

@@ -90,43 +90,40 @@ Use the same controller for many Sessions. Don't store a current Session on the
 The controller, Session, and thread have different lifetimes:
 
 - **Controller**: A shared host for configuration and runtime services. Initialize it once and reuse it.
-- **Session**: An isolated live runtime for one user, task, or concurrent work scope. It owns the active mode, model, state, event bus, run state, grants, and current thread binding.
+- **Session**: An isolated live runtime for one user, task, or concurrent piece of work, addressed by its session id. It owns the active mode, model, state, event bus, run state, grants, and current thread binding.
 - **Thread**: A stored conversation containing messages and thread settings. Threads can survive controller and process recreation when you configure storage.
 
 A Session is live state. Arbitrary [`session.state`](https://mastra.ai/reference/agent-controller/session), permission grants, pending approvals, and active runs don't automatically survive process recreation. Thread messages and selected thread settings, including the active mode and the current model, can persist through storage, but switching modes doesn't change the model.
 
 ## Sessions and threads
 
-`createSession()` is get-or-create by `resourceId` and optional `scope`:
+`createSession()` is get-or-create by session `id`. The `resourceId` names who owns the session's threads and resource-scoped memory. When you omit `id`, it defaults to `resourceId`:
 
 ```typescript
 const webSession = await controller.createSession({
+  id: 'user-123:web',
   resourceId: 'user-123',
-  scope: 'web',
 })
 
-const sameWebSession = await controller.createSession({
-  resourceId: 'user-123',
-  scope: 'web',
-})
+const sameWebSession = await controller.getSession('user-123:web')
 
 const workerSession = await controller.createSession({
+  id: 'user-123:background-worker',
   resourceId: 'user-123',
-  scope: 'background-worker',
 })
 
 console.log(webSession === sameWebSession) // true
 console.log(webSession === workerSession) // false
 ```
 
-Sessions with different scopes have separate event buses, run loops, state, mode and model selections, and current thread bindings. Their stored threads still belong to the shared `resourceId`.
+Sessions with different ids have separate event buses, run loops, state, mode and model selections, and current thread bindings. Their stored threads and resource-scoped memory still belong to the shared `resourceId`, so listing threads by resource returns both sessions' threads.
 
 Pass `threadId` when the host must bind the Session to an exact thread. The controller switches to the existing thread or creates it with that ID when it's missing. This behavior also applies when `createSession()` returns a cached Session:
 
 ```typescript
 const session = await controller.createSession({
+  id: 'user-123:web',
   resourceId: 'user-123',
-  scope: 'web',
   threadId: 'support-ticket-42',
 })
 ```
@@ -430,9 +427,9 @@ channels: {
     const install = await installs.authorize(requestContext.get('teamId'))
 
     return controller.createSession({
+      id: `${install.id}:${thread.id}`,
       resourceId: thread.resourceId,
       threadId: thread.id,
-      scope: install.id,
       ownerId: controller.id,
       requestContext,
     })
@@ -440,7 +437,7 @@ channels: {
 }
 ```
 
-Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Pass `threadId: thread.id` so the session opens on the mapped thread. Without it, a session that has tags or a `projectPath` doesn't treat the mapped thread as its own, so it creates an extra empty thread before switching to the mapped one. Sessions are get-or-create for each `resourceId` and `scope` combination. Pass `scope` when one thread needs separate sessions for each installation or principal.
+Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Pass `threadId: thread.id` so the session opens on the mapped thread. Without it, a session that has tags or a `projectPath` doesn't treat the mapped thread as its own, so it creates an extra empty thread before switching to the mapped one. Sessions are get-or-create by `id`. Give each installation or principal its own `id` when one thread needs separate sessions.
 
 Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
 
@@ -490,7 +487,7 @@ Subscriptions are isolated by Session. Events from another Session on the same c
 
 ### Client-side sessions
 
-[`client.getAgentController(key).session(resourceId, scope?)`](https://mastra.ai/reference/client-js/agent-controller) returns a session client bound to one resource. Pass the key the controller is registered under in `new Mastra({ agentControllers })`, which can differ from the controller's `id`. Sessions are get-or-create on the server, so `create()` resumes an existing conversation instead of forking it. Pass `scope` when one resource needs independent sessions, such as one per git worktree:
+[`client.getAgentController(key).session(sessionId)`](https://mastra.ai/reference/client-js/agent-controller) returns a session client addressed by its session id. Pass the key the controller is registered under in `new Mastra({ agentControllers })`, which can differ from the controller's `id`. Sessions are get-or-create on the server, so `create()` resumes an existing conversation instead of forking it. Pass `resourceId` to `create()` when several sessions share one resource; otherwise the resource defaults to the session id:
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
@@ -513,7 +510,7 @@ const subscription = await session.subscribe({
 subscription.unsubscribe()
 ```
 
-`subscribe()` takes an options object and is async, unlike the in-process listener. Its promise resolves once the stream is established and rejects when it can't connect. A rejected call leaves nothing running in the background. `reconnect: true` re-establishes a stream that drops after it was established, with exponential backoff. A connection that goes silent without closing, for example after the device sleeps, counts as a drop once no data, including server heartbeats, arrives for `idleTimeoutMs` (default `60000`).
+`subscribe()` takes an options object and is async, unlike the in-process listener. Its promise resolves once the stream is established and rejects when it can't connect. A rejected call leaves nothing running in the background. `reconnect: true` re-establishes a stream that drops after it was established, with exponential backoff. A connection that stays open but stops delivering data, for example after the device sleeps, counts as a drop once no data, including server heartbeats, arrives for `idleTimeoutMs` (default `60000`).
 
 The server doesn't replay events missed while the stream was down, so read `session.state()` from `onReconnect` for the current mode, model, and thread. The client surface has no `session.displayState.get()`.
 

package/dist/docs/references/docs-harness-schedules.md

@@ -171,13 +171,13 @@ const mastra = new Mastra({
       return { prompt: `Status as of ${trigger.firedAt.toISOString()}` }
     },
     onFinish: async ({ agentId, outcome, runId }) => {
-      // Runs on any non-error, non-abort outcome
+      // Runs on any non-error, non-abort outcome. For a threaded schedule, this is the hand-off, not the end of the run
     },
     onError: async ({ agentId, phase, error }) => {
-      // Runs when prepare, the signal, or the agent run threw
+      // Runs when prepare or the signal threw, or a threadless run failed without aborting
     },
     onAbort: async ({ agentId, runId }) => {
-      // Runs when the run was aborted mid-stream
+      // Runs when a threadless run was aborted
     },
   },
 })
@@ -186,9 +186,11 @@ const mastra = new Mastra({
 The hooks are:
 
 - `prepare`: runs before the fire. Return an object to override fire-time parameters such as `prompt` or `threadId`, `null` to skip the fire, or `undefined` to use the stored defaults.
-- `onFinish`: runs once per trigger that reached a non-error, non-abort terminal state.
-- `onError`: runs after a failure in `prepare` or the signal. It also runs when the agent run fails.
-- `onAbort`: runs when the run was aborted mid-stream.
+- `onFinish`: runs once per trigger that reached a non-error, non-abort outcome. When a threaded schedule starts a new run, it runs with `outcome: 'succeeded'` as soon as the run starts, not when it finishes.
+- `onError`: runs after a failure in `prepare` or the signal. For a schedule without a `threadId`, it also runs when the agent run fails with an error that isn't an abort.
+- `onAbort`: runs when the run of a schedule without a `threadId` was aborted.
+
+For a schedule with a `threadId`, the worker sends the prompt to the thread and doesn't wait for the run. Errors and aborts after the run starts surface on that thread's run, not through `onError` or `onAbort`.
 
 Every hook context includes `agentId` (the agent the schedule fired for) alongside `schedule` and `trigger`.
 

package/dist/docs/references/reference-client-js-agent-controller.md

@@ -81,11 +81,19 @@ Returns the controller's workspace status.
 
 Returns: `Promise<AgentControllerWorkspaceStatus>`
 
-### `session(resourceId, scope?)`
+### `session(sessionId)`
 
-Returns an `AgentControllerSession` bound to one resource. Sessions are get-or-create on the server, so calling `create()` on the same `resourceId` and `scope` resumes the existing conversation instead of forking it.
+Returns an `AgentControllerSession` addressed by its session id. Every request goes to `/agent-controller/:controllerId/sessions/:sessionId/...`. Sessions are get-or-create on the server, so calling `create()` with the same `sessionId` resumes the existing conversation instead of forking it.
 
-Pass `scope` to address an independent session over the same `resourceId`. Sessions that share a `resourceId` but use different scopes each get their own run loop, thread binding, mode, model, and state. A common pattern is one session per git worktree with the worktree path as the scope. The scope travels on every request as a `sessionScope` query parameter.
+Sessions that share a resource but use different session ids each get their own run loop, thread binding, mode, model, and state. Their stored threads and resource-scoped memory belong to the shared resource. Pass the resource to `create()`:
+
+```typescript
+const runA = client.getAgentController('code').session('run-a')
+await runA.create({ resourceId: 'factory-1' })
+
+const runB = client.getAgentController('code').session('run-b')
+await runB.create({ resourceId: 'factory-1' })
+```
 
 ## Session methods
 
@@ -93,6 +101,8 @@ Pass `scope` to address an independent session over the same `resourceId`. Sessi
 
 Creates or resumes the session.
 
+**resourceId** (`string`): Memory resource that owns the session's threads. Defaults to the session id, so a session created with only an id keeps one resource of its own.
+
 **tags** (`Record<string, string>`): Scopes initial thread selection. A thread is a resume candidate only when its metadata matches every tag.
 
 **threadId** (`string`): Binds the session to one exact thread, creating it with that ID when it does not exist.

package/dist/docs/references/reference-client-js-mastra-client.md

@@ -61,7 +61,7 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **listAgentControllers()** (`Promise<AgentControllerInfo[]>`): Returns the agent controllers hosted on the connected Mastra instance. Each entry's id is the key the controller is registered under in new Mastra({ agentControllers }).
 
-**getAgentController(controllerId)** (`AgentController`): Retrieves a specific agent controller by the key it is registered under in new Mastra({ agentControllers }), which can differ from the controller id. .session(resourceId) returns a session client; call await session.create() to create or resume the server session.
+**getAgentController(controllerId)** (`AgentController`): Retrieves a specific agent controller by the key it is registered under in new Mastra({ agentControllers }), which can differ from the controller id. .session(sessionId) returns a session client; call await session.create() to create or resume the server session.
 
 **listMemoryThreads(params)** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a resourceId and an agentId.
 

package/dist/docs/references/reference-client-js-observability.md

@@ -90,7 +90,7 @@ const result = await mastraClient.querySpans({
 console.log(result.spans)
 ```
 
-Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt` or `endedAt`, ascending or descending, and defaults to descending start time.
+Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt`, `endedAt`, or `timeToFirstChunkMs`, ascending or descending, and defaults to descending start time. Spans without a `timeToFirstChunkMs` value sort last in both directions.
 
 | Fields                                                                                                                                       | Operators                                                                                                  |
 | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -98,14 +98,14 @@ Pages default to 100 rows and allow at most 1,000. The response is `{ spans, pag
 | `organizationId`, `resourceId`, `runId`, `sessionId`, `userId`, `requestId`, `serviceName`, `experimentId`, `environment`, `executionSource` | Same string operators                                                                                      |
 | Entity, parent entity and root entity `Type`, `Id`, `Name`, `VersionId` fields, such as `parentEntityId`                                     | Same string operators                                                                                      |
 | `name`, `spanType`, `status`                                                                                                                 | Same string operators; `name` also accepts `matches` / `notMatches` for normalized whole words and phrases |
-| `startedAt`, `endedAt`, `durationMs`                                                                                                         | Comparisons, membership and presence                                                                       |
+| `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                   | Comparisons, membership and presence                                                                       |
 | `error`                                                                                                                                      | `exists`, `notExists`                                                                                      |
 
 Combine predicates with `and`, `or` and `not`. Membership uses `{ op: 'in', value: { path: 'spanType' }, set: ['agent_run', 'tool_call'] }`. A span's status is `error` when it has an error and `success` otherwise.
 
 Each summary includes identity, context, entity lineage, status, timestamps, `durationMs`, model/provider and input/output/error previews. Model/provider are available in returned rows but aren't filterable.
 
-The additional identity, context and parent/root entity filters require an updated storage adapter. With an older adapter, requests using these filters return a structured `422` error.
+Check `capabilities.spanQueryContextFields` from `getObservabilityCapabilities()` before using the additional identity, context and parent/root entity filters. A missing or false value means these filters aren't available. With an older adapter, requests using these filters return a structured `422` error.
 
 DuckDB returns `null` for parent/root entity type, ID and name, and for `executionSource`. Equality filters on these fields match no spans. Parent/root entity version IDs remain available.
 

package/dist/docs/references/reference-observability-tracing-advanced-queries.md

@@ -21,18 +21,20 @@ For hosted traces, see [Query observability data on Mastra Platform](https://mas
 
 The configured observability store must support each API. Call `getObservabilityCapabilities()` or `GET /api/observability/capabilities` and check these flags before showing a feature:
 
-| Capability                   | Store feature                     | Enables                                                                                |
-| ---------------------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
-| `traceQuery`                 | `trace-query`                     | `queryTraces()`                                                                        |
-| `traceAggregate`             | `trace-aggregate`                 | `aggregateTraces()`                                                                    |
-| `traceQueryRootDuration`     | `trace-query-root-duration`       | Trace-scope `durationMs` predicates                                                    |
-| `traceQueryTimeToFirstChunk` | `trace-query-time-to-first-chunk` | `timeToFirstChunkMs` predicates and results                                            |
-| `traceQueryContextIds`       | `trace-query-context-ids`         | `runId`, `sessionId`, `userId`, and `organizationId` predicates                        |
-| `traceQueryRootSpanFields`   | `trace-query-root-span-fields`    | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
-| `traceQueryDiscovery`        | `trace-query-discovery`           | [Field and value discovery](#discover-fields-and-values)                               |
-| `traceQueryTenantScope`      | `trace-query-tenant-scope`        | [Trusted tenant scope](#trusted-tenant-scope)                                          |
-
-A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Root span `name` and `spanType` are the exception and return `422` with a `field_not_allowed` issue.
+| Capability                       | Store feature                          | Enables                                                                                |
+| -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------- |
+| `traceQuery`                     | `trace-query`                          | `queryTraces()`                                                                        |
+| `traceAggregate`                 | `trace-aggregate`                      | `aggregateTraces()`                                                                    |
+| `traceQueryRootDuration`         | `trace-query-root-duration`            | Trace-scope `durationMs` predicates                                                    |
+| `traceQueryTimeToFirstChunk`     | `trace-query-time-to-first-chunk`      | `timeToFirstChunkMs` predicates and results                                            |
+| `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs`                                                      |
+| `traceQueryContextIds`           | `trace-query-context-ids`              | `runId`, `sessionId`, `userId`, and `organizationId` predicates                        |
+| `traceQueryRootSpanFields`       | `trace-query-root-span-fields`         | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
+| `traceQueryRootEntityId`         | `trace-query-root-entity-id`           | Trace-scope `entityId` predicates, dimensions, and `countDistinct` measures            |
+| `traceQueryDiscovery`            | `trace-query-discovery`                | [Field and value discovery](#discover-fields-and-values)                               |
+| `traceQueryTenantScope`          | `trace-query-tenant-scope`             | [Trusted tenant scope](#trusted-tenant-scope)                                          |
+
+A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Root span `name`, `spanType`, and `entityId` are the exception and return `422` with a `field_not_allowed` issue.
 
 ## Select traces
 
@@ -75,7 +77,7 @@ Span clauses examine the current root span and current child spans. The root `ti
 
 | Predicate context | Fields                                                                                                                                                                                                 | Operators                                                                  |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`                                         | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityId`, `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`                             | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Trace metadata    | `metadata.<key>`                                                                                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Trace             | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Trace             | `tags`                                                                                                                                                                                                 | `includes`, `notIncludes`, `exists`, `notExists`                           |
@@ -84,7 +86,7 @@ Span clauses examine the current root span and current child spans. The root `ti
 | Span              | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Span              | `error`                                                                                                                                                                                                | `exists`, `notExists`                                                      |
 
-Trace-scope `name` and `spanType` read the current root span, so `{ op: 'eq', left: { path: 'spanType' }, right: { literal: 'workflow_run' } }` selects traces started by a workflow run. Inside `spans.some` or `spans.none`, the same fields match any span in the trace.
+Trace-scope `name`, `spanType`, and `entityId` read the current root span, so `{ op: 'eq', left: { path: 'spanType' }, right: { literal: 'workflow_run' } }` selects traces started by a workflow run. Inside `spans.some` or `spans.none`, the same fields match any span in the trace.
 
 Compose predicates with `{ op: 'and', args: [...] }`, `{ op: 'or', args: [...] }`, and `{ op: 'not', arg: ... }`. Comparison predicates place a field reference on the left and a literal on the right. Membership predicates use a field reference in `value` and a homogeneous literal array in `set`. Tag predicates name the stored tag collection in `path`. `includes` and `notIncludes` also take one tag in `value`, while `exists` and `notExists` take only `op` and `path`. See [Filter by tags](#filter-by-tags). Text predicates use the comparison shape with a string literal. See [Filter by text](#filter-by-text).
 
@@ -128,7 +130,13 @@ const slowFirstChunk = {
 
 The value is `null` when the span didn't stream a chunk, for example a tool call or a workflow run. A `null` value counts as missing, so it matches `notExists` and never matches ordered predicates. A value of `0` isn't missing. It means the first chunk arrived in the same millisecond the span started.
 
-Trace query results include the root span's `timeToFirstChunkMs`, and `querySpans()` results include each span's value. Sorting by this field isn't supported. Stores advertise support through the `trace-query-time-to-first-chunk` feature, and the server reports it as the `traceQueryTimeToFirstChunk` capability. Against an older store, results omit the field, a predicate on it returns `501` before storage runs, and field discovery omits it.
+Trace query results include the root span's `timeToFirstChunkMs`, and `querySpans()` results include each span's value. Stores advertise support through the `trace-query-time-to-first-chunk` feature, and the server reports it as the `traceQueryTimeToFirstChunk` capability. Against an older store, results omit the field, a predicate on it returns `501` before storage runs, and field discovery omits it.
+
+#### Sort by time to first chunk
+
+Pass `orderBy: [{ field: 'timeToFirstChunkMs', direction: 'desc' }]` to list the slowest first chunks first. Traces sort by the root span's value. Missing values sort last in both directions, and `0` sorts as a value. Ties break by `traceId` for traces and by span identity for `querySpans()`.
+
+Stores advertise the sort through the `trace-query-time-to-first-chunk-sort` feature, and the server reports it as the `traceQueryTimeToFirstChunkSort` capability. Against an older store, the sort returns `501` before storage runs.
 
 #### Filter by context identifiers
 
@@ -437,16 +445,16 @@ curl --request POST \
 
 ### Request fields
 
-| Field        | Required | Description                                                                                                                                     |
-| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `timeRange`  | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, and `from` must be earlier than `to`. |
-| `where`      | No       | Recursive trace predicate. Supports scalar conditions and `spans.some` or `spans.none` clauses.                                                 |
-| `orderBy`    | No       | One item ordering results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode.      |
-| `page`       | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                            |
-| `pagination` | No       | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100.                                         |
-| `mode`       | No       | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`.                                                                |
-| `after`      | No       | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark.                           |
-| `limit`      | No       | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100.                                                            |
+| Field        | Required | Description                                                                                                                                                       |
+| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `timeRange`  | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, and `from` must be earlier than `to`.                   |
+| `where`      | No       | Recursive trace predicate. Supports scalar conditions and `spans.some` or `spans.none` clauses.                                                                   |
+| `orderBy`    | No       | One item ordering results by `startedAt`, `endedAt`, or `timeToFirstChunkMs`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode. |
+| `page`       | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                                              |
+| `pagination` | No       | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100.                                                           |
+| `mode`       | No       | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`.                                                                                  |
+| `after`      | No       | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark.                                             |
+| `limit`      | No       | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100.                                                                              |
 
 Unknown fields are rejected. Requests can't select a projection, declare joins, request counts or measures, or control authorization. Use [`aggregateTraces()`](#aggregate-traces) for counts and measures. Request bodies are limited to 256 KiB.
 
@@ -657,12 +665,13 @@ Unknown fields are rejected. Aggregation isn't paginated. Narrow the selection,
 
 Dimensions read the current root span of each selected trace:
 
-| Dimension                                                                             | Notes                                                                                                            |
-| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `entityType`, `entityName`, `environment`, `status`, `serviceName`, `executionSource` | Root span attributes.                                                                                            |
-| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId`     | Context identifiers recorded on the root span.                                                                   |
-| `name`, `spanType`                                                                    | Root span name and type. Requires the `traceQueryRootSpanFields` capability.                                     |
-| `metadata.<key>`                                                                      | One non-empty top-level metadata key. Values are trimmed. Missing, empty, and non-string values group as `null`. |
+| Dimension                                                                             | Notes                                                                                                                                |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `entityType`, `entityName`, `environment`, `status`, `serviceName`, `executionSource` | Root span attributes.                                                                                                                |
+| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId`     | Context identifiers recorded on the root span.                                                                                       |
+| `name`, `spanType`                                                                    | Root span name and type. Requires the `traceQueryRootSpanFields` capability.                                                         |
+| `entityId`                                                                            | Root span entity ID. Groups traces that have no `entityName`, such as scorer runs. Requires the `traceQueryRootEntityId` capability. |
+| `metadata.<key>`                                                                      | One non-empty top-level metadata key. Values are trimmed. Missing, empty, and non-string values group as `null`.                     |
 
 Every dimension except `serviceName`, `executionSource`, and `experimentId` is also a trace-scope `where` field, so you can drill into a group by adding its values to the predicate. `traceId`, `spanId`, `runId`, and `requestId` aren't groupable. Traces with no value for a dimension form their own group with a `null` value.