@mastra/client-js 1.54.1-alpha.1 → 1.54.1-alpha.3

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.54.1-alpha.1"
+  version: "1.54.1-alpha.3"
 ---
 
 ## When to use
@@ -54,7 +54,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [Reference: Versioning](references/reference-editor-versioning.md) - Editor versions stored agents and prompt blocks. Database-backed resources use draft and publish operations.
 - [Client SDK](references/reference-migrations-upgrade-to-v1-client.md) - Client SDK changes align with server-side API updates, including utility renames, updated pagination, and type naming conventions.
 - [Reference: Metric queries](references/reference-observability-metrics-queries.md) - Metric queries read raw and aggregated metric data from the observability storage domain. For exporter and storage setup, see the Metrics overview.
-- [Advanced trace queries](references/reference-observability-tracing-trace-query.md) - Query completed traces, thread identities, and spans with recursive predicates, numbered pages, keyset cursors, and delta polling.
+- [Trace queries](references/reference-observability-tracing-trace-query.md) - Find completed traces by trace fields and related spans. Filter results, paginate, poll for updates, and discover query fields.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -45,7 +45,7 @@ const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId)
 
 ## Listing traces for a list view
 
-`listTracesLight()` returns the same rows as a trace list, without the `input`, `output` and `attributes` payloads. Each row carries a short `inputPreview` string instead, so a list can render a preview column without transferring the whole prompt, plus `threadId` and `resourceId` for the memory context columns.
+`listTracesLight()` returns the same rows as a trace list, without the `input`, `output` and `attributes` payloads. Each row carries short `inputPreview`, `outputPreview` and `errorPreview` strings instead (at most 100 characters, ending with `…` when cut), so a list can render preview columns without transferring the whole payload, plus `threadId` and `resourceId` for the memory context columns.
 
 Prefer it whenever you are rendering many traces at once, and fetch the full record only when a row is opened:
 
@@ -65,9 +65,9 @@ const selected = await mastraClient.getTrace(list.spans[0].traceId)
 
 It accepts the same filtering, ordering and delta-polling arguments as `listTraces()`. Use `listTraces()` when you actually need the full span payloads.
 
-## Querying traces and threads
+## Querying traces
 
-`queryTraces()` finds completed logical traces using trace fields and conditions over related spans, scores, or feedback. Every query requires an ISO timestamp range of at most 31 days.
+`queryTraces()` finds completed logical traces using trace fields and conditions over related spans. Every query requires an ISO timestamp range.
 
 ```typescript
 const result = await mastraClient.queryTraces({
@@ -76,12 +76,12 @@ const result = await mastraClient.queryTraces({
     to: '2026-08-08T00:00:00.000Z',
   },
   where: {
-    scores: {
+    spans: {
       some: {
         op: 'and',
         args: [
-          { op: 'eq', left: { path: 'scorerId' }, right: { literal: 'factuality' } },
-          { op: 'lt', left: { path: 'score' }, right: { literal: 0.6 } },
+          { op: 'eq', left: { path: 'spanType' }, right: { literal: 'tool_call' } },
+          { op: 'exists', path: 'error' },
         ],
       },
     },
@@ -89,6 +89,8 @@ const result = await mastraClient.queryTraces({
 })
 ```
 
+See [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for request fields, predicates, limits, response shapes, and errors.
+
 ### Load a page and poll for traces
 
 `queryTraces()` supports keyset traversal with `page`, numbered pages with `pagination`, and delta polling with `mode: 'delta'`. Use one mode per request. To migrate from `listTracesLight()`, read `traces` instead of `spans` and retain the numbered page's `deltaCursor`:
@@ -114,7 +116,7 @@ const changes = await mastraClient.queryTraces({
 
 Merge `changes.traces` by `traceId`, retain `changes.deltaCursor`, and continue while `changes.delta.hasMore` is `true`. Keep the same time range and predicate across polls. Only completed traces are returned; polling doesn't guarantee notifications for related-record updates, deletions, or traces that stop matching.
 
-See [Delta polling](https://mastra.ai/reference/observability/tracing/trace-query) for bootstrap behavior, cursor lifetime, retention, and a complete polling loop. `queryTraceThreads()` remains keyset-only.
+See [Delta polling](https://mastra.ai/reference/observability/tracing/trace-query) for bootstrap behavior, cursor lifetime, retention, and a complete polling loop.
 
 ### Discover trace-query fields and values
 
@@ -134,7 +136,7 @@ const fields = await mastraClient.getTraceQueryFields({
 })
 ```
 
-Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A global picker can fetch `trace`, `spans`, `scores`, and `feedback` in parallel.
+Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A field picker can fetch the `trace` and `spans` scopes in parallel.
 
 Call `getTraceQueryValues()` only after selecting a field with `valueSuggestions: true`:
 
@@ -162,89 +164,6 @@ Suggestions are bounded and advisory. Manual values remain valid when suggestion
 
 A discovery timeout rejects with `504 TRACE_QUERY_EXECUTION_TIMEOUT`. Backend memory or resource exhaustion rejects with `503 TRACE_QUERY_RESOURCE_LIMIT`. Neither error contains partial suggestions; truncation flags are only present on successful, completely ranked responses.
 
-`queryTraceThreads()` returns thread identities derived from observability traces after applying eligibility and cross-trace conditions. It doesn't read or return memory thread records or messages. In this example, one production trace can have the low factuality score while another production trace in the same thread has the clinician correction:
-
-```typescript
-const result = await mastraClient.queryTraceThreads({
-  traces: {
-    timeRange: {
-      from: '2026-08-01T00:00:00.000Z',
-      to: '2026-08-08T00:00:00.000Z',
-    },
-    where: {
-      op: 'eq',
-      left: { path: 'environment' },
-      right: { literal: 'production' },
-    },
-  },
-  where: {
-    op: 'and',
-    args: [
-      {
-        traces: {
-          some: {
-            scores: {
-              some: {
-                op: 'lt',
-                left: { path: 'score' },
-                right: { literal: 0.6 },
-              },
-            },
-          },
-        },
-      },
-      {
-        traces: {
-          some: {
-            feedback: {
-              some: {
-                op: 'eq',
-                left: { path: 'feedbackType' },
-                right: { literal: 'clinician-correction' },
-              },
-            },
-          },
-        },
-      },
-    ],
-  },
-})
-
-// { threads: [{ threadId: 'thread-123' }], page: { next: null } }
-```
-
-The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse trace and thread queries have a configurable 15-second execution timeout.
-
-See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, thread qualification semantics, cursor pagination, response shapes, and errors.
-
-## Querying spans
-
-`querySpans()` returns one row per matching completed span across traces. Use it to list the spans themselves. `queryTraces()` with a `spans.some` predicate returns the traces that contain a matching span instead. Every query requires an ISO timestamp range of at most 31 days.
-
-```typescript
-const result = await mastraClient.querySpans({
-  timeRange: {
-    from: '2026-10-01T00:00:00.000Z',
-    to: '2026-10-02T00:00:00.000Z',
-  },
-  where: {
-    op: 'eq',
-    left: { path: 'spanType' },
-    right: { literal: 'tool_call' },
-  },
-  orderBy: [{ field: 'startedAt', direction: 'desc' }],
-  page: { limit: 50 },
-})
-
-// { spans: [{ traceId, spanId, name, spanType, status, durationMs, cost, ... }], page: { next } }
-```
-
-Pass `result.page.next` back as `page.after` with the same time range, filter, and ordering to load the next page. Each row contains identifiers, display fields, input and output previews, and the span's model cost. Use `getSpan()` to load the full span.
-
-Span queries are optional for observability stores. Check `capabilities.spanQuery` from `getObservabilityCapabilities()` before calling `querySpans()`, and treat a missing value as unsupported. Unsupported servers reject with `501 SPAN_QUERY_UNSUPPORTED`.
-
-See [Query individual spans](https://mastra.ai/reference/observability/tracing/trace-query) for filters, ordering, cursors, cost states, limits, and errors.
-
 ## Deleting traces
 
 Delete traces and their associated spans, metrics, logs, scores, and feedback:
@@ -393,7 +312,7 @@ const ratingPercentiles = await mastraClient.getFeedbackPercentiles({
 
 ## Related
 
-- [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query): Query completed traces with recursive predicates
+- [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query): Query completed traces with recursive predicates
 - [Feedback guide](https://mastra.ai/docs/observability/feedback): Learn how to create, list, and query feedback
 - [Feedback reference](https://mastra.ai/reference/observability/feedback): Review feedback schemas and HTTP routes
 - [Agents API](https://mastra.ai/reference/client-js/agents): Learn about agent interactions that generate traces