@mastra/client-js 1.60.0-alpha.0 → 1.60.0-alpha.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/dist/client.d.ts +15 -4
  2. package/dist/client.d.ts.map +1 -1
  3. package/dist/docs/SKILL.md +5 -5
  4. package/dist/docs/assets/SOURCE_MAP.json +6 -6
  5. package/dist/docs/references/docs-harness-schedules.md +3 -1
  6. package/dist/docs/references/docs-signals-sending-signals.md +3 -1
  7. package/dist/docs/references/integrations-auth-clerk.md +46 -7
  8. package/dist/docs/references/integrations-auth-neon.md +217 -0
  9. package/dist/docs/references/integrations-auth-supabase.md +46 -7
  10. package/dist/docs/references/integrations-auth-workos.md +54 -15
  11. package/dist/docs/references/reference-client-js-agents.md +4 -4
  12. package/dist/docs/references/reference-client-js-observability.md +36 -6
  13. package/dist/docs/references/reference-observability-tracing-advanced-queries.md +49 -59
  14. package/dist/index.cjs +87 -39
  15. package/dist/index.cjs.map +1 -1
  16. package/dist/index.d.ts +1 -1
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +87 -39
  19. package/dist/index.js.map +1 -1
  20. package/dist/resources/agent.d.ts +18 -11
  21. package/dist/resources/agent.d.ts.map +1 -1
  22. package/dist/resources/observability-route-types.d.ts +8 -10
  23. package/dist/resources/observability-route-types.d.ts.map +1 -1
  24. package/dist/resources/observability.d.ts +12 -2
  25. package/dist/resources/observability.d.ts.map +1 -1
  26. package/dist/route-types.generated.d.ts +343 -212
  27. package/dist/route-types.generated.d.ts.map +1 -1
  28. package/dist/types.d.ts +5 -3
  29. package/dist/types.d.ts.map +1 -1
  30. package/package.json +3 -3
  31. package/dist/docs/references/reference-migrations-upgrade-to-v1-client.md +0 -341
@@ -4,9 +4,48 @@
4
4
 
5
5
  # Supabase
6
6
 
7
+ Use Supabase with Mastra in two ways:
8
+
9
+ - **Agent tools** let an agent query tables, call database functions, and manage storage and auth users in Supabase through [Mastra Connect](https://mastra.ai/docs/mastra-platform/connect).
10
+ - **[Server authentication](#server-authentication)** verifies requests to your Mastra server with Supabase, using the `@mastra/auth-supabase` package.
11
+
12
+ ## Connect
13
+
14
+ Before you start, complete the [Connect setup](https://mastra.ai/docs/mastra-platform/connect) to install `@mastra/connect` and configure your platform project.
15
+
16
+ ### Agent tools
17
+
18
+ Give agents tools to query and change table rows, call database functions, and manage storage buckets, files, and auth users in Supabase.
19
+
20
+ Connect an account with the `supabase` provider ID. Run this command from the directory that contains your `.env` file:
21
+
22
+ ```bash
23
+ mastra connect add supabase
24
+ ```
25
+
26
+ Then pass [`tools()`](https://mastra.ai/reference/connect/tools) to the agent and select the provider:
27
+
28
+ ```typescript
29
+ import { Agent } from '@mastra/core/agent'
30
+ import { tools } from '@mastra/connect'
31
+
32
+ export const supabaseAgent = new Agent({
33
+ id: 'supabase-agent',
34
+ name: 'Supabase agent',
35
+ instructions:
36
+ 'You help people query and change table rows, call database functions, and manage storage buckets, files, and auth users in Supabase.',
37
+ model: '__GATEWAY_OPENAI_MODEL_LUNA__',
38
+ tools: tools({ providers: ['supabase'] }),
39
+ })
40
+ ```
41
+
42
+ The agent gets 27 Supabase tools, with keys such as `supabase_copy_storage_object`. See [Supabase tools](https://mastra.ai/reference/connect/providers) for the full list, and the [`tools()` parameters](https://mastra.ai/reference/connect/tools) to restrict tools or require approval before a call runs.
43
+
44
+ ## Server authentication
45
+
7
46
  The `@mastra/auth-supabase` package provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `auth` option.
8
47
 
9
- ## Prerequisites
48
+ ### Prerequisites
10
49
 
11
50
  This example uses Supabase Auth. Make sure to add your Supabase credentials to your `.env` file and ensure your Supabase project is properly configured.
12
51
 
@@ -17,7 +56,7 @@ SUPABASE_ANON_KEY=your-anon-key
17
56
 
18
57
  > **Note:** Review your Supabase Row Level Security (RLS) settings to ensure proper data access controls.
19
58
 
20
- ## Installation
59
+ ### Installation
21
60
 
22
61
  Before you can use the `MastraAuthSupabase` class you have to install the `@mastra/auth-supabase` package.
23
62
 
@@ -45,7 +84,7 @@ yarn add @mastra/auth-supabase@latest
45
84
  bun add @mastra/auth-supabase@latest
46
85
  ```
47
86
 
48
- ## Usage example
87
+ ### Usage example
49
88
 
50
89
  ```typescript
51
90
  import { Mastra } from '@mastra/core'
@@ -65,11 +104,11 @@ export const mastra = new Mastra({
65
104
  >
66
105
  > Visit [MastraAuthSupabase](https://mastra.ai/reference/auth/supabase) for all available configuration options.
67
106
 
68
- ## Client-side setup
107
+ ### Client-side setup
69
108
 
70
109
  When using Supabase auth, you'll need to retrieve the access token from Supabase on the client side and pass it to your Mastra requests.
71
110
 
72
- ### Retrieving the access token
111
+ #### Retrieving the access token
73
112
 
74
113
  Use the Supabase client to authenticate users and retrieve their access token:
75
114
 
@@ -88,7 +127,7 @@ const accessToken = authTokenResponse.data?.session?.access_token
88
127
 
89
128
  > **Note:** Refer to the [Supabase documentation](https://supabase.com/docs/guides/auth) for other authentication methods like OAuth, magic links, and more.
90
129
 
91
- ## Configuring `MastraClient`
130
+ ### Configuring `MastraClient`
92
131
 
93
132
  When `auth` is enabled, all requests made with `MastraClient` must include a valid Supabase access token in the `Authorization` header:
94
133
 
@@ -107,7 +146,7 @@ export const mastraClient = new MastraClient({
107
146
  >
108
147
  > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
109
148
 
110
- ### Making authenticated requests
149
+ #### Making authenticated requests
111
150
 
112
151
  Once `MastraClient` is configured with the Supabase access token, you can send authenticated requests:
113
152
 
@@ -4,9 +4,48 @@
4
4
 
5
5
  # WorkOS
6
6
 
7
+ Use WorkOS with Mastra in two ways:
8
+
9
+ - **Agent tools** let an agent manage WorkOS organizations, users, and SSO connections through [Mastra Connect](https://mastra.ai/docs/mastra-platform/connect).
10
+ - **[Server authentication](#server-authentication)** verifies requests to your Mastra server with WorkOS, using the `@mastra/auth-workos` package.
11
+
12
+ ## Connect
13
+
14
+ Before you start, complete the [Connect setup](https://mastra.ai/docs/mastra-platform/connect) to install `@mastra/connect` and configure your platform project.
15
+
16
+ ### Agent tools
17
+
18
+ Give agents tools to manage organizations, users, memberships, invitations, SSO connections, and directories in WorkOS.
19
+
20
+ Connect an account with the `workos` provider ID. Run this command from the directory that contains your `.env` file:
21
+
22
+ ```bash
23
+ mastra connect add workos
24
+ ```
25
+
26
+ Then pass [`tools()`](https://mastra.ai/reference/connect/tools) to the agent and select the provider:
27
+
28
+ ```typescript
29
+ import { Agent } from '@mastra/core/agent'
30
+ import { tools } from '@mastra/connect'
31
+
32
+ export const workosAgent = new Agent({
33
+ id: 'workos-agent',
34
+ name: 'WorkOS agent',
35
+ instructions:
36
+ 'You help people manage organizations, users, memberships, invitations, SSO connections, and directories in WorkOS.',
37
+ model: '__GATEWAY_OPENAI_MODEL_LUNA__',
38
+ tools: tools({ providers: ['workos'] }),
39
+ })
40
+ ```
41
+
42
+ The agent gets 40 WorkOS tools, with keys such as `workos_create_connection`. See [WorkOS tools](https://mastra.ai/reference/connect/providers) for the full list, and the [`tools()` parameters](https://mastra.ai/reference/connect/tools) to restrict tools or require approval before a call runs.
43
+
44
+ ## Server authentication
45
+
7
46
  The `@mastra/auth-workos` package provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `auth` option.
8
47
 
9
- ## Prerequisites
48
+ ### Prerequisites
10
49
 
11
50
  This example uses WorkOS authentication. Make sure to:
12
51
 
@@ -24,7 +63,7 @@ WORKOS_CLIENT_ID=client_...
24
63
  >
25
64
  > For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
26
65
 
27
- ## Installation
66
+ ### Installation
28
67
 
29
68
  Before you can use the `MastraAuthWorkos` class you have to install the `@mastra/auth-workos` package.
30
69
 
@@ -52,9 +91,9 @@ yarn add @mastra/auth-workos@latest
52
91
  bun add @mastra/auth-workos@latest
53
92
  ```
54
93
 
55
- ## Usage examples
94
+ ### Usage examples
56
95
 
57
- ### Basic usage with environment variables
96
+ #### Basic usage with environment variables
58
97
 
59
98
  ```typescript
60
99
  import { Mastra } from '@mastra/core'
@@ -67,7 +106,7 @@ export const mastra = new Mastra({
67
106
  })
68
107
  ```
69
108
 
70
- ### Custom configuration
109
+ #### Custom configuration
71
110
 
72
111
  ```typescript
73
112
  import { Mastra } from '@mastra/core'
@@ -83,13 +122,13 @@ export const mastra = new Mastra({
83
122
  })
84
123
  ```
85
124
 
86
- ## Configuration
125
+ ### Configuration
87
126
 
88
- ### Default authorization
127
+ #### Default authorization
89
128
 
90
129
  By default, `MastraAuthWorkos` grants access to any authenticated WorkOS user. The authorization check succeeds when the resolved user object contains both a Mastra user ID and a WorkOS user ID.
91
130
 
92
- ### FGA membership loading
131
+ #### FGA membership loading
93
132
 
94
133
  > **Note:** FGA requires a Mastra Enterprise Edition (EE) license in production. It works without a license in development. See [what requires an EE license](https://mastra.ai/docs/license). [Contact sales](https://mastra.ai/contact) for more information.
95
134
 
@@ -112,7 +151,7 @@ const workosFga = new MastraFGAWorkos({
112
151
 
113
152
  When `fetchMemberships` is `false`, Mastra skips the extra WorkOS `listOrganizationMemberships()` call on each authenticated request.
114
153
 
115
- ### Service tokens and custom JWT templates
154
+ #### Service tokens and custom JWT templates
116
155
 
117
156
  For machine-to-machine or service-account access, you can configure `MastraAuthWorkos` to trust verified bearer-token claims from a WorkOS custom JWT template.
118
157
 
@@ -133,7 +172,7 @@ const workosAuth = new MastraAuthWorkos({
133
172
 
134
173
  This is useful when your JWT template already includes the exact FGA context Mastra needs, such as `organizationMembershipId`, tenant IDs, or service-principal identifiers. When `trustJwtClaims` is enabled, Mastra can fall back to those verified claims if a bearer token isn't meant to round-trip through `workos.userManagement.getUser()`.
135
174
 
136
- ### Custom authorization
175
+ #### Custom authorization
137
176
 
138
177
  If you need stricter authorization, subclass `MastraAuthWorkos` and override `authorizeUser()`:
139
178
 
@@ -155,11 +194,11 @@ const workosAuth = new AdminOnlyWorkosAuth({
155
194
 
156
195
  Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
157
196
 
158
- ## Client-side setup
197
+ ### Client-side setup
159
198
 
160
199
  When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.
161
200
 
162
- ### Installing WorkOS SDK
201
+ #### Installing WorkOS SDK
163
202
 
164
203
  First, install the WorkOS SDK in your application:
165
204
 
@@ -187,7 +226,7 @@ yarn add @workos-inc/node
187
226
  bun add @workos-inc/node
188
227
  ```
189
228
 
190
- ### Exchanging code for access token
229
+ #### Exchanging code for access token
191
230
 
192
231
  After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
193
232
 
@@ -208,7 +247,7 @@ export const authenticateWithWorkos = async (code: string, clientId: string) =>
208
247
 
209
248
  > **Note:** Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
210
249
 
211
- ## Configuring `MastraClient`
250
+ ### Configuring `MastraClient`
212
251
 
213
252
  When `auth` is enabled, all requests made with `MastraClient` must include a valid WorkOS access token in the `Authorization` header:
214
253
 
@@ -229,7 +268,7 @@ export const createMastraClient = (accessToken: string) => {
229
268
  >
230
269
  > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
231
270
 
232
- ### Making authenticated requests
271
+ #### Making authenticated requests
233
272
 
234
273
  Once `MastraClient` is configured with the WorkOS access token, you can send authenticated requests:
235
274
 
@@ -914,9 +914,9 @@ const agent = await mastraClient.createStoredAgent({
914
914
  })
915
915
  ```
916
916
 
917
- #### Durable stored agents
917
+ #### Resumable streams for stored agents
918
918
 
919
- Set `durable` to run the agent as a [durable agent](https://mastra.ai/docs/harness/durable-agents) once the server hydrates it. Pass `true` to accept the defaults, or an object to tune the durable loop:
919
+ Set `durable` to configure [resumable streams](https://mastra.ai/docs/agents/resumable-streams) on the hydrated plain agent. Pass `true` to enable streams, `false` to disable them, or an object to tune stream cleanup:
920
920
 
921
921
  ```typescript
922
922
  const agent = await mastraClient.createStoredAgent({
@@ -927,11 +927,11 @@ const agent = await mastraClient.createStoredAgent({
927
927
  provider: 'openai',
928
928
  name: 'gpt-5.4',
929
929
  },
930
- durable: { maxSteps: 50, cleanupTimeoutMs: 0 },
930
+ durable: { cleanupTimeoutMs: 0 },
931
931
  })
932
932
  ```
933
933
 
934
- Only serializable options are accepted. The durable cache and pubsub are inherited from the server's `Mastra` instance. If it has no distributed cache or pubsub configured, durability is process-local. Automatic recovery is still configured in code through `recovery.durableAgents`.
934
+ Only serializable options are accepted, with cache and pubsub inherited from the server's `Mastra` instance. Existing stored agents with `durable: true` also use this field for resumable streams only. To retain durable execution and checkpoint recovery, register a code agent wrapped with `createDurableAgent({ agent })`.
935
935
 
936
936
  ### `getStoredAgent()`
937
937
 
@@ -115,7 +115,7 @@ if (capabilities.spanAggregate) {
115
115
 
116
116
  The request and response structure follows `aggregateTraces()`, with direct span predicates and span dimensions such as `spanType`, `name`, and `parentEntityName`. Token and cost measures belong to the span that recorded the usage and aren't added to parent spans. Check `capabilities.spanAggregate` before calling, and `capabilities.spanAggregateModelDimensions` before grouping or counting distinct values by `model` or `provider`. With an older adapter, those requests return `501`.
117
117
 
118
- Both `aggregateTraces()` and `aggregateSpans()` accept `timeToFirstToken.*` and `timeToFirstChunk.*` measures when `capabilities.aggregateTimeToFirstMeasures` is `true`. Spans and traces without a recorded value are skipped, never counted as 0. See [Time to first token and chunk measures](https://mastra.ai/reference/observability/tracing/advanced-queries).
118
+ Both `aggregateTraces()` and `aggregateSpans()` accept time to first token (TTFT) and time to first chunk (TTFC) measures, `timeToFirstToken.*` and `timeToFirstChunk.*`, when `capabilities.aggregateTimeToFirstMeasures` is `true`. Spans and traces without a recorded value are skipped, never counted as 0. See [Time to first chunk (TTFC)](https://mastra.ai/reference/observability/tracing/advanced-queries) and [Time to first token (TTFT)](https://mastra.ai/reference/observability/tracing/advanced-queries).
119
119
 
120
120
  See [Aggregate spans](https://mastra.ai/reference/observability/tracing/advanced-queries) for selection, dimensions, per-span usage, and how to list the spans behind a group.
121
121
 
@@ -371,11 +371,17 @@ const result = await mastraClient.deleteTraces({
371
371
  traceIds: ['trace-1', 'trace-2'],
372
372
  })
373
373
 
374
- console.log(result.success)
374
+ if ('accepted' in result) {
375
+ console.log('Deletion requested')
376
+ } else {
377
+ console.log(result.success)
378
+ }
375
379
  ```
376
380
 
377
381
  Each request accepts up to 1,000 trace IDs and no tenant scope fields. Signals that aren't linked to a trace are preserved. Traces created by experiments are deleted like any other trace.
378
382
 
383
+ The client supports two response shapes: OSS returns `{ success: true }` after its delete operation, while a Platform backend that supports queued batch deletion returns `202 { accepted: true }` after accepting cleanup. Acceptance doesn't mean records have disappeared from reads, so check the response before reporting deletion as complete. Using these client methods with Platform requires a deployment that supports the batch deletion endpoints.
384
+
379
385
  ## Scoring traces
380
386
 
381
387
  Score specific traces using registered scorers for evaluation:
@@ -403,6 +409,16 @@ const scores = await mastraClient.listScoresBySpan({
403
409
  })
404
410
  ```
405
411
 
412
+ ## Get a score by ID
413
+
414
+ Use `getScore()` to retrieve one observability score:
415
+
416
+ ```typescript
417
+ const { score } = await mastraClient.getScore('score-id-123')
418
+ ```
419
+
420
+ The response is `{ score: record | null }`. A missing score returns HTTP 200 with `{ score: null }`. The return type is `GetScoreResponse`, exported from `@mastra/client-js`.
421
+
406
422
  ## Creating scores
407
423
 
408
424
  Create a score for a trace, optionally identifying a span within it:
@@ -422,7 +438,19 @@ const response = await mastraClient.createScore({
422
438
 
423
439
  ## Feedback
424
440
 
425
- Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the configured API server. Create methods support OSS and Platform. Full replacement uses Platform's PUT endpoint. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
441
+ Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the configured API server. Create methods support OSS and Platform. Full replacement is supported by Platform and OSS servers with feedback replacement support. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
442
+
443
+ ### Get feedback by ID
444
+
445
+ Use `getFeedback()` to retrieve one feedback record:
446
+
447
+ ```typescript
448
+ const { feedback } = await mastraClient.getFeedback('feedback-id-123')
449
+ ```
450
+
451
+ The response is `{ feedback: record | null }`. A missing record returns HTTP 200 with `{ feedback: null }`. The return type is `GetFeedbackResponse`, exported from `@mastra/client-js`.
452
+
453
+ Both getters accept an unencoded ID and encode it as a URL path segment. They use the client's configured API prefix, credentials, and headers. Record timestamps are ISO strings in the JSON response.
426
454
 
427
455
  ### Creating feedback
428
456
 
@@ -470,9 +498,9 @@ Create responses contain `success` and optional `data` with the generated or sup
470
498
 
471
499
  Explicit modes require server support. Older servers may ignore `contextMode`. Deploy Platform's supplied-context support before sending `"provided"` there.
472
500
 
473
- ### Replacing feedback on Platform
501
+ ### Replacing feedback
474
502
 
475
- `replaceFeedback()` sends a full replacement to `PUT /api/observability/feedback/:feedbackId`. Include the original `feedbackId`, `traceId`, and normalized `timestamp`, along with all feedback fields to retain. This method targets Platform. OSS server doesn't implement this replacement endpoint.
503
+ `replaceFeedback()` sends a full replacement to `PUT /api/observability/feedback/:feedbackId`. Include the original `feedbackId`, `traceId`, and normalized `timestamp`, along with all feedback fields to retain. Platform and OSS servers with feedback replacement support accept this method. OSS returns `501` when its storage adapter doesn't support replacement. For OSS, check `capabilities.feedbackReplacement` before offering edits. A missing capability means unavailable.
476
504
 
477
505
  ```typescript
478
506
  await mastraClient.replaceFeedback({
@@ -487,7 +515,7 @@ await mastraClient.replaceFeedback({
487
515
  })
488
516
  ```
489
517
 
490
- Use the normalized timestamp from the create response's `data` when available. A changed timestamp identifies a different Platform record. The client preserves the replacement body across retries, but each accepted PUT retry is a new replacement and can supersede another edit. Pass `{ retries: 0, anchorRetryTimeoutMs: 0 }` as the second argument to disable automatic retries.
518
+ Use the normalized timestamp from the create response's `data` when available. OSS rejects changes to the original trace or timestamp with `409`. Platform uses the timestamp as part of record identity, so preserve it there too. The client preserves the replacement body across retries, but each accepted PUT retry is a new replacement and can supersede another edit. Pass `{ retries: 0, anchorRetryTimeoutMs: 0 }` as the second argument to disable automatic retries.
491
519
 
492
520
  ### Deleting feedback and scores
493
521
 
@@ -507,6 +535,8 @@ await mastraClient.deleteScores({
507
535
  })
508
536
  ```
509
537
 
538
+ Both methods return `{ success: boolean }` from OSS or `{ accepted: true }` from a Platform backend that supports queued batch deletion. See [Deleting traces](#deleting-traces) for response handling. Accepted records can remain readable until cleanup runs. Platform uses authenticated organization/project scope, which request-body scope fields can't override.
539
+
510
540
  ### Listing feedback
511
541
 
512
542
  Retrieve paginated feedback records with optional filters:
@@ -35,6 +35,7 @@ The configured observability store must support each API. Call `getObservability
35
35
  | -------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36
36
  | `traceQuery` | `trace-query` | `queryTraces()` |
37
37
  | `spanQuery` | `span-query` | `querySpans()` |
38
+ | `spanQueryDurationSort` | `span-query-duration-sort` | `orderBy` on `durationMs` in `querySpans()` |
38
39
  | `spanQueryContextFields` | `span-query-context-fields` | Additional identity, context, and parent/root entity predicates in span queries and aggregates |
39
40
  | `spanQueryModelFields` | `span-query-model-fields` | `model` and `provider` predicates in span queries and aggregates |
40
41
  | `traceAggregate` | `trace-aggregate` | `aggregateTraces()` |
@@ -128,39 +129,9 @@ This top-level predicate doesn't inspect child spans. In contrast, `spans.some`
128
129
 
129
130
  Trace queries exclude incomplete roots before evaluating predicates. As a result, `{ op: 'notExists', path: 'durationMs' }` doesn't find running traces or malformed roots without a usable `endedAt`.
130
131
 
131
- #### Filter by time to first chunk
132
+ #### Filter and sort by time to first chunk or token
132
133
 
133
- `timeToFirstChunkMs` is the time in milliseconds from a span's start to the first chunk of its model response. Agent run and model spans record it when the model streams a response. At trace scope, the field reads the current root span's value. Inside `spans.some` or `spans.none`, it reads each related span.
134
-
135
- This predicate finds traces with a model call that took more than 2 seconds to stream its first chunk:
136
-
137
- ```typescript
138
- const slowFirstChunk = {
139
- spans: {
140
- some: {
141
- op: 'and',
142
- args: [
143
- { op: 'eq', left: { path: 'spanType' }, right: { literal: 'model_generation' } },
144
- { op: 'gt', left: { path: 'timeToFirstChunkMs' }, right: { literal: 2000 } },
145
- ],
146
- },
147
- },
148
- }
149
- ```
150
-
151
- 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.
152
-
153
- 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.
154
-
155
- #### Sort by time to first chunk
156
-
157
- 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()`.
158
-
159
- 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.
160
-
161
- #### Filter and sort by time to first token
162
-
163
- `timeToFirstTokenMs` is the time in milliseconds from the start of a model call, the provider request itself, to the first chunk that call streams. It leaves out the work Mastra does before calling the model, such as input processors. The value is measured once, on the model inference span that streamed the chunk. Model step, model generation, and agent run spans carry the value of the nearest such inference below them: each step takes its own, and the generation and agent run take the first step's. A step can run more than one inference, for example a fallback model or a retry that opens a new inference span. The value then comes from the first inference that streamed a chunk. A fallback attempt that failed ends its inference span with its error. That span has a value only if it streamed a chunk first. Mastra storage keeps the value in its own column and leaves it out of the stored `attributes`. Read it from the span's `timeToFirstTokenMs` field. When an in-process agent retries a failed model call, the AI SDK retries inside a single inference span. The value then includes the failed attempt and the retry wait. Durable agents open one inference span per attempt and don't. At trace scope, the field reads the current root span's value. Inside `spans.some` or `spans.none`, it reads each related span.
134
+ `timeToFirstChunkMs` holds a span's [time to first chunk (TTFC)](#time-to-first-chunk-ttfc), and `timeToFirstTokenMs` holds its [time to first token (TTFT)](#time-to-first-token-ttft). At trace scope, the fields read the root span's value. Inside `spans.some` or `spans.none`, they read each related span. Both fields also work in `orderBy`.
164
135
 
165
136
  This predicate finds traces whose root agent waited more than 2 seconds for the model's first token:
166
137
 
@@ -168,9 +139,7 @@ This predicate finds traces whose root agent waited more than 2 seconds for the
168
139
  const slowFirstToken = { op: 'gt', left: { path: 'timeToFirstTokenMs' }, right: { literal: 2000 } }
169
140
  ```
170
141
 
171
- `null`, `0`, and missing values follow the same rules as `timeToFirstChunkMs`. Pass `orderBy: [{ field: 'timeToFirstTokenMs', direction: 'desc' }]` to list the slowest first tokens first, with the same ordering and tie-breaks.
172
-
173
- Stores advertise support through the `trace-query-time-to-first-token` feature and the sort through the `trace-query-time-to-first-token-sort` feature. The server reports them as the `traceQueryTimeToFirstToken` and `traceQueryTimeToFirstTokenSort` capabilities. Against an older store, results omit the field, and a predicate or sort on it returns `501` before storage runs.
142
+ See [Missing first chunk and token values](#missing-first-chunk-and-token-values) for `null`, `0`, and the capabilities each use needs.
174
143
 
175
144
  #### Filter by outcome
176
145
 
@@ -570,7 +539,7 @@ A query using keyset pagination returns lightweight completed traces and a curso
570
539
 
571
540
  The response includes `name`, `createdAt`, identity fields, `metadata`, and input/output/error previews. Supported nullable fields remain present with `null` when no value was recorded. Fields that require an optional store feature are omitted when the store lacks that feature. Previews summarize payloads; retrieve the full trace for complete input, output, and error details.
572
541
 
573
- `timeToFirstChunkMs` and `timeToFirstTokenMs` are present only when the configured store supports them. See [Filter by time to first chunk](#filter-by-time-to-first-chunk) and [Filter and sort by time to first token](#filter-and-sort-by-time-to-first-token). `outcome`, `stopReason`, and `stopReasonContext` read the root span and are present only when the store supports the `traceQueryOutcomeFields` capability. They're `null` when the root span didn't record them. See [Filter by outcome](#filter-by-outcome).
542
+ `timeToFirstChunkMs` and `timeToFirstTokenMs` are present only when the configured store supports them. See [Filter and sort by time to first chunk or token](#filter-and-sort-by-time-to-first-chunk-or-token). `outcome`, `stopReason`, and `stopReasonContext` read the root span and are present only when the store supports the `traceQueryOutcomeFields` capability. They're `null` when the root span didn't record them. See [Filter by outcome](#filter-by-outcome).
574
543
 
575
544
  The response doesn't include the related spans that matched the predicate. Use [`getTrace()`](https://mastra.ai/reference/client-js/observability) to load the full trace after selecting a result.
576
545
 
@@ -704,7 +673,7 @@ const result = await mastraClient.querySpans({
704
673
  console.log(result.spans)
705
674
  ```
706
675
 
707
- 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`, `timeToFirstChunkMs`, or `timeToFirstTokenMs`, ascending or descending, and defaults to descending start time. Spans without a value for the `timeToFirstChunkMs` or `timeToFirstTokenMs` sort field sort last in both directions.
676
+ 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`, `durationMs`, `timeToFirstChunkMs`, or `timeToFirstTokenMs`, ascending or descending, and defaults to descending start time. Spans without a value for the `timeToFirstChunkMs` or `timeToFirstTokenMs` sort field sort last in both directions.
708
677
 
709
678
  | Fields | Operators |
710
679
  | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -838,6 +807,12 @@ Every dimension except `executionSource` is also a trace-scope `where` field, so
838
807
  | `countDistinct.<field>` | Number of distinct non-null values of a dimension or `traceId`, such as `countDistinct.userId`. |
839
808
  | `duration.avg`, `duration.min`, `duration.max` | Root span duration in milliseconds. |
840
809
  | `duration.p50`, `duration.p90`, `duration.p95`, `duration.p99` | Root span duration percentile in milliseconds. Percentiles can be approximate, depending on the store. |
810
+ | `timeToFirstChunk.avg`, `timeToFirstChunk.min`, `timeToFirstChunk.max` | Root span time to first chunk in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
811
+ | `timeToFirstChunk.p50`, `timeToFirstChunk.p90`, `timeToFirstChunk.p95`, `timeToFirstChunk.p99` | Root span time to first chunk percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
812
+ | `timeToFirstChunk.count` | Number of traces whose root span recorded a time to first chunk. Requires the `aggregateTimeToFirstMeasures` capability. |
813
+ | `timeToFirstToken.avg`, `timeToFirstToken.min`, `timeToFirstToken.max` | Root span time to first token in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
814
+ | `timeToFirstToken.p50`, `timeToFirstToken.p90`, `timeToFirstToken.p95`, `timeToFirstToken.p99` | Root span time to first token percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
815
+ | `timeToFirstToken.count` | Number of traces whose root span recorded a time to first token. Requires the `aggregateTimeToFirstMeasures` capability. |
841
816
  | `errorCount` | Number of traces whose root span recorded an error. |
842
817
  | `errorRate` | `errorCount` divided by `count`, from 0 to 1. |
843
818
  | `tokens.input.sum`, `tokens.input.avg` | Input tokens. |
@@ -846,12 +821,6 @@ Every dimension except `executionSource` is also a trace-scope `where` field, so
846
821
  | `tokens.reasoning.sum`, `tokens.reasoning.avg` | Reasoning output tokens. |
847
822
  | `tokens.cached.sum`, `tokens.cached.avg` | Input tokens read from the provider's cache. |
848
823
  | `cost.sum`, `cost.avg` | Estimated model cost. |
849
- | `timeToFirstToken.avg`, `timeToFirstToken.min`, `timeToFirstToken.max` | Root span time to first token in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
850
- | `timeToFirstToken.p50`, `timeToFirstToken.p90`, `timeToFirstToken.p95`, `timeToFirstToken.p99` | Root span time to first token percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
851
- | `timeToFirstToken.count` | Number of traces whose root span recorded a time to first token. Requires the `aggregateTimeToFirstMeasures` capability. |
852
- | `timeToFirstChunk.avg`, `timeToFirstChunk.min`, `timeToFirstChunk.max` | Root span time to first chunk in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
853
- | `timeToFirstChunk.p50`, `timeToFirstChunk.p90`, `timeToFirstChunk.p95`, `timeToFirstChunk.p99` | Root span time to first chunk percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
854
- | `timeToFirstChunk.count` | Number of traces whose root span recorded a time to first chunk. Requires the `aggregateTimeToFirstMeasures` capability. |
855
824
 
856
825
  Numeric measures over metadata aren't supported.
857
826
 
@@ -872,16 +841,11 @@ When you request any `cost.*` measure, every row also includes a `cost` object:
872
841
 
873
842
  `cost.sum` and `cost.avg` are `null` when the group has no priced traces or `unit` is `'mixed'`. A coverage below 1 means the cost understates the group's spend. The `cost` object isn't a measure, so `having` and `orderBy` can't reference it.
874
843
 
875
- #### Time to first token and chunk measures
876
-
877
- `timeToFirstToken.*` and `timeToFirstChunk.*` read the root span's `timeToFirstTokenMs` and `timeToFirstChunkMs`, the same values [`queryTraces()`](#query-traces) returns. An agent run copies them from the first model generation of its own loop:
878
-
879
- - `timeToFirstChunk.*` is measured from the agent run's start, so it includes work done before the first model call, such as input processors and memory recall.
880
- - `timeToFirstToken.*` is the time to first token of the model call that streamed that first chunk.
844
+ ### Time to first chunk (TTFC)
881
845
 
882
- Traces without a value are skipped, never counted as 0. This includes traces whose agent run didn't stream, and traces rooted in a workflow, since a workflow run records neither value. `avg`, `min`, `max`, and the percentiles are `null` for a group where no trace has a value, and `.count` is the number of traces that do have one. Percentiles can be approximate, depending on the store.
846
+ Time to first chunk (TTFC) is how long a caller waits for the first streamed chunk. `timeToFirstChunkMs` is the time from a span's start to the first chunk of its model response. Agent run and model spans record it when the model streams a response. On an agent run, it's measured from the run's start and includes work done before the first model call, such as input processors and memory recall.
883
847
 
884
- Stores advertise support through the `aggregate-time-to-first-measures` feature, and the server reports it as the `aggregateTimeToFirstMeasures` capability. Against an older store, a request for any of these measures returns `501` before storage runs, and [field discovery](#discover-fields-and-values) omits them.
848
+ The `timeToFirstChunk.*` measures aggregate the root span's `timeToFirstChunkMs`, the same value [`queryTraces()`](#query-traces) returns. To filter or sort by it, see [Filter and sort by time to first chunk or token](#filter-and-sort-by-time-to-first-chunk-or-token).
885
849
 
886
850
  ```typescript
887
851
  const { capabilities } = await mastraClient.getObservabilityCapabilities()
@@ -900,6 +864,39 @@ if (capabilities.traceAggregate && capabilities.aggregateTimeToFirstMeasures) {
900
864
  }
901
865
  ```
902
866
 
867
+ ### Time to first token (TTFT)
868
+
869
+ Time to first token (TTFT) is the time in milliseconds from the start of a model call, the provider request itself, to the first chunk that call streams. Unlike TTFC, it leaves out the work Mastra does before calling the model, such as input processors.
870
+
871
+ The `timeToFirstToken.*` measures aggregate the root span's `timeToFirstTokenMs`. To filter or sort by it, see [Filter and sort by time to first chunk or token](#filter-and-sort-by-time-to-first-chunk-or-token). Compare TTFC with TTFT to see how much of an agent's wait comes from work before the model call.
872
+
873
+ ### First chunk and token span types
874
+
875
+ These span types record TTFC and TTFT:
876
+
877
+ - `model_inference`: each provider call.
878
+ - `model_step`: each step of a generation, with the values of the inference that streamed the step's first chunk.
879
+ - `model_generation`: the whole generation, with the values of its first streamed inference only. A multi-step generation, such as a tool loop, reports only its first call.
880
+ - `agent_run`: the agent run, with the values of the first model generation of its own loop. Its TTFC is measured from the run's start.
881
+
882
+ Other spans, such as tool calls and workflow runs, record neither value. A trace rooted in a workflow has no TTFC or TTFT at trace scope.
883
+
884
+ TTFT is measured once, on the `model_inference` span that streamed the chunk. A step with a fallback model or a retry takes the value of its first inference that streamed a chunk. A failed fallback attempt has a value only if it streamed a chunk before failing. An in-process agent retries a failed model call inside a single inference span. Its TTFT then includes the failed attempt and the retry wait. Durable agents open one inference span per attempt.
885
+
886
+ Mastra storage keeps TTFT in its own column, not in the stored `attributes`. Read it from the span's `timeToFirstTokenMs` field.
887
+
888
+ ### Missing first chunk and token values
889
+
890
+ The value is `null` when the span didn't stream a chunk. A value of `0` isn't missing. It means the first chunk arrived in the same millisecond the span started.
891
+
892
+ - In predicates, `null` counts as missing. It matches `notExists` and never matches ordered predicates.
893
+ - In `orderBy`, missing values sort last in both directions, and `0` sorts as a value.
894
+ - In aggregates, spans and traces without a value are skipped, never counted as 0.
895
+
896
+ Filtering, sorting, and aggregating each require a store feature. See [Check capabilities](#check-capabilities) for the `traceQueryTimeToFirstChunk`, `traceQueryTimeToFirstChunkSort`, `traceQueryTimeToFirstToken`, `traceQueryTimeToFirstTokenSort`, and `aggregateTimeToFirstMeasures` flags. Against an older store, results omit the unsupported fields, a request that uses them returns `501` before storage runs, and [field discovery](#discover-fields-and-values) omits them.
897
+
898
+ For `timeToFirstChunk.*` and `timeToFirstToken.*`, `avg`, `min`, `max`, and the percentiles are `null` for a group where no trace has a value, and `.count` is the number of traces that do have one. Percentiles can be approximate, depending on the store. The measures require the `aggregateTimeToFirstMeasures` capability.
899
+
903
900
  ### Filter and order groups
904
901
 
905
902
  A group is one distinct combination of `groupBy` values. `having`, `orderBy`, and `limit` operate on groups and use each group's measures over the whole time range, even when `interval` is set. The server applies `having` first, then orders the remaining groups and keeps the first `limit`. `truncated` is `true` when more groups remained than `limit`.
@@ -1031,14 +1028,7 @@ Aggregation uses the same span predicates as [`querySpans()`](#query-spans), wit
1031
1028
 
1032
1029
  `count` counts selected spans in each group or time bucket. Buckets use each span's `startedAt`. `duration.*` measures read the span's own duration, and `errorCount` and `errorRate` read whether the span itself recorded an error.
1033
1030
 
1034
- `timeToFirstToken.*` and `timeToFirstChunk.*` read the span's own `timeToFirstTokenMs` and `timeToFirstChunkMs`, and skip spans without a value. Several span types record them:
1035
-
1036
- - `model_inference`: each provider call. Filter to this type for per-call time to first token.
1037
- - `model_step`: each step of a generation, with the values of the inference that streamed the step's first chunk.
1038
- - `model_generation`: the whole generation, with the values of its first streamed inference only. A multi-step generation, such as a tool loop, reports only its first call.
1039
- - `agent_run`: the agent run, with time to first chunk measured from the run's start. Filter to this type for latency as the caller of each agent sees it.
1040
-
1041
- Without a `spanType` filter, one agent call contributes its agent run, its model generation, and every model step and model inference.
1031
+ `timeToFirstToken.*` and `timeToFirstChunk.*` read the span's own `timeToFirstTokenMs` and `timeToFirstChunkMs`. See [First chunk and token span types](#first-chunk-and-token-span-types) for which spans record them. Filter to `model_inference` for per-call TTFT, or to `agent_run` for latency as the caller of each agent sees it. Without a `spanType` filter, one agent call contributes its agent run, its model generation, and every model step and model inference.
1042
1032
 
1043
1033
  On ClickHouse, a direct `spanType` `eq` or `in` predicate, or one immediately inside an `and`, can select the smaller branch table. All selected types must be branch types: `agent_run`, `workflow_run`, `processor_run`, `scorer_run`, `rag_ingestion`, `tool_call`, or `mcp_tool_call`. Every requested field must be available in that table. An equivalent `or` predicate doesn't select this optimization. The branch path can differ from `querySpans()`:
1044
1034