@mastra/server 1.75.0-alpha.2 → 1.75.0-alpha.4

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-server
 description: Documentation for @mastra/server. Use when working with @mastra/server APIs, configuration, or implementation.
 metadata:
   package: "@mastra/server"
-  version: "1.75.0-alpha.2"
+  version: "1.75.0-alpha.4"
 ---
 
 ## When to use
@@ -24,7 +24,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Reference
 
-- [Advanced trace queries](references/reference-observability-tracing-trace-query.md) - Query completed traces and thread identities with recursive predicates, numbered pages, keyset cursors, and delta polling.
+- [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.
 - [Reference: createRoute()](references/reference-server-create-route.md) - Use createRoute() to define type-safe Mastra server routes with Zod validation for requests and responses, plus handler context and OpenAPI metadata.
 - [Reference: MastraServer](references/reference-server-mastra-server.md) - The MastraServer abstract class is the base for all server adapters. Extend this class to create adapters for frameworks other than Hono or Express.
 - [Reference: Server routes](references/reference-server-routes.md) - Server adapters register these routes when you call server.init(). All routes are prefixed with the prefix option if configured.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.75.0-alpha.2",
+  "version": "1.75.0-alpha.4",
   "package": "@mastra/server",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-observability-tracing-trace-query.md

@@ -6,10 +6,121 @@
 
 Use `queryTraces()` or `POST /api/observability/traces/query` to find completed logical traces that match trace fields and related span, score, or feedback records. Use `queryTraceThreads()` or `POST /api/observability/threads/query` to find thread identities that qualify across multiple eligible traces.
 
-Both endpoints use the same authentication as other observability routes and require the `observability:read` permission. The configured observability store must support the requested trace-query or thread-query operation.
+Use `querySpans()` or `POST /api/observability/spans/query` to list the individual completed spans that match a span predicate.
+
+All three endpoints use the same authentication as other observability routes and require the `observability:read` permission. The configured observability store must support the requested trace-query, thread-query, or span-query operation.
 
 > **Thread grouping is deprecated:** The `group` option remains supported until the next major release. Use [`queryTraceThreads()`](https://mastra.ai/reference/client-js/observability) to retrieve matching thread identities in new code.
 
+## Query individual spans
+
+`querySpans()` returns one row per matching completed span across traces, including matching child spans. Use it to list the spans themselves, for example every failed tool call in the last day.
+
+`queryTraces()` with a `spans.some` predicate answers a different question. It returns the traces that contain at least one matching span, and it doesn't identify which spans matched. Both use the same span fields and operators.
+
+```typescript
+const timeRange = {
+  from: '2026-10-01T00:00:00.000Z',
+  to: '2026-10-02T00:00:00.000Z',
+}
+const where = {
+  op: 'and',
+  args: [
+    { op: 'eq', left: { path: 'spanType' }, right: { literal: 'tool_call' } },
+    { op: 'eq', left: { path: 'status' }, right: { literal: 'error' } },
+  ],
+} as const
+
+const firstPage = await mastraClient.querySpans({
+  timeRange,
+  where,
+  orderBy: [{ field: 'startedAt', direction: 'desc' }],
+  page: { limit: 50 },
+})
+
+if (firstPage.page.next) {
+  const secondPage = await mastraClient.querySpans({
+    timeRange,
+    where,
+    orderBy: [{ field: 'startedAt', direction: 'desc' }],
+    page: { limit: 50, after: firstPage.page.next },
+  })
+}
+```
+
+The HTTP route accepts the same body:
+
+```bash
+curl --request POST \
+  --url http://localhost:4111/api/observability/spans/query \
+  --header 'Authorization: Bearer <token>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "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" } },
+    "page": { "limit": 50 }
+  }'
+```
+
+Span queries are optional for observability stores. Call `mastraClient.getObservabilityCapabilities()` and check `capabilities.spanQuery` before showing a span list. Treat a missing `spanQuery` value as unsupported, because older servers don't report it. A server whose store or `@mastra/core` version doesn't support span queries returns `501` with code `SPAN_QUERY_UNSUPPORTED`.
+
+The other statuses match trace queries: `400` for malformed JSON or a malformed cursor, `409` for a cursor that doesn't match the query, `413` for a body over 256 KiB, `422` with code `TRACE_QUERY_INVALID` and structured `issues` for an invalid query, `503` with code `TRACE_QUERY_RESOURCE_LIMIT` when a page exceeds a resource limit, and `504` with code `TRACE_QUERY_EXECUTION_TIMEOUT` when the database deadline is exceeded.
+
+The server applies [trusted tenant scope](#trusted-tenant-scope) to span queries the same way it does for trace queries. A cursor created under one scope and reused under another returns `409`.
+
+### Query individual spans through storage
+
+The observability domain in DuckDB and the PostgreSQL and ClickHouse v-next stores supports `querySpans(plan)`. Check `storage.getFeatures()?.includes('span-query')` before using this optional storage method.
+
+Build the plan in trusted backend code:
+
+```typescript
+import { planSpanQuery } from '@mastra/core/storage'
+
+const storage = await mastra.getStorage()?.getStore('observability')
+if (!storage?.getFeatures()?.includes('span-query')) {
+  throw new Error('This store does not support span queries')
+}
+
+const plan = planSpanQuery({
+  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' },
+  },
+  page: { limit: 50 },
+})
+
+const { spans, page } = await storage.querySpans(plan)
+```
+
+This example uses local, unscoped storage. For a shared database, pass `{ scope: { organizationId, resourceId } }` as the second argument to `planSpanQuery()`, using identifiers resolved by your backend's authorization. The request body can't supply trusted scope. Apply the same authorization when loading full span details with `getSpan({ traceId, spanId })`.
+
+Span queries use the scalar fields and operators available inside `queryTraces()`'s `spans.some` predicate. They don't accept related-record clauses. Nested attributes require support in the shared predicate contract and each store.
+
+The `timeRange` applies to each span's `startedAt`, includes `from`, excludes `to`, and can cover at most 31 days. Sort by `startedAt` or `endedAt`, in either direction. The default is `startedAt` descending. A page contains up to 1,000 rows, with a default of 100. Pass `page.next` back as `page.after` with the same filters, time range, scope, and ordering. Cursors use scope and span identifiers to break timestamp ties. They aren't a snapshot across requests. New completions can appear when the view is refreshed.
+
+Each row contains span and trace identifiers, display fields, duration, status, and input/output previews of at most 256 Unicode characters. Truncation flags indicate when a preview is incomplete. Stores select the page before loading previews and cost. Full payloads remain available through the existing span detail method.
+
+The `cost` field describes only that span's model-token cost:
+
+- `available` includes `amount` and `currency`. Zero is a valid amount.
+- `missing` means no matching model metrics were found.
+- `unavailable` means metrics exist but a complete, unambiguous cost can't be established.
+
+Directional token totals supply the cost. Overlapping detail metrics aren't added again. A provider-supplied `query_total` cost is counted once. Partial pricing, conflicting currencies, and ambiguous totals produce `unavailable`.
+
+Current-record selection runs before mutable filters. PostgreSQL and ClickHouse select the greatest completed `endedAt`. PostgreSQL breaks ties with its ingestion cursor. DuckDB reconstructs the earliest start event and selects the latest ingested completed event, matching its existing span-predicate behavior. Time bounds are checked again after reconstruction. ClickHouse uses its existing completion-only, insert-only model, where equal-version retries must contain identical records. Querying spans doesn't add a table or materialized view.
+
+Queries have a 15-second default execution deadline. PostgreSQL and ClickHouse use their existing `traceQuery.timeoutMs` setting. ClickHouse also caps each query at 512 MiB. A page with more than 50,000 matching model metrics fails with a resource-limit error instead of returning partial cost. A small page size limits returned rows, but doesn't limit the number of records the database must examine.
+
 ## Query traces with the client SDK
 
 Pass the query to `queryTraces()`:
@@ -718,7 +829,7 @@ PostgreSQL and ClickHouse stop advanced trace and thread queries after 15 second
 
 ## Limitations
 
-Both operations consider completed traces only. They don't support running traces, custom projections, embedded evidence, summaries, aggregations, measures, or custom grouping. Numbered trace pages include a total count.
+Trace and thread queries consider completed traces only, and span queries consider completed spans only. They don't support running traces, custom projections, embedded evidence, summaries, aggregations, measures, or custom grouping. Numbered trace pages include a total count.
 
 ## Related
 

package/dist/{observability-new-endpoints-lNC3o66-.js → observability-new-endpoints-DQuhr8aL.js}

@@ -3,8 +3,8 @@ import { a as wrapSchemaForQueryParams, i as pickParams, n as createRoute } from
 import { d as MASTRA_USER_ROLES_KEY, l as MASTRA_USER_KEY, m as isStudioClientTypeHeader } from "./constants-0jFCWoex.js";
 import { handleError } from "./server/handlers/error.js";
 import { paginationArgsSchema as paginationArgsSchema$1 } from "./server/handlers/observability-list-query-schemas.js";
-import { NEW_ROUTE_DEFS, NO_OBSERVABILITY_STORAGE_CAPABILITIES, OBSERVABILITY_LIST_ENDPOINTS, OBSERVABILITY_TRACE_QUERY_TENANT_SCOPE_UPGRADE_MESSAGE, assertObservabilityDeltaSupported, assertObservabilityThreadQuerySupported, assertObservabilityTraceAggregateSupported, assertObservabilityTraceQueryContextIdsSupported, assertObservabilityTraceQueryDiscoverySupported, assertObservabilityTraceQueryRootDurationSupported, assertObservabilityTraceQuerySupported, assertObservabilityTraceQueryTenantScopeSupported, createObservabilityListQuerySchema, getObservabilityStorageCapabilities, getObservabilityStore, isTraceQueryContextIdField, supportsObservabilityTraceQueryContextIds, supportsObservabilityTraceQueryRootDuration, supportsTraceAggregateCore, supportsTraceQueryDiscoveryCore, withDiscoveryFallback } from "./server/handlers/observability-shared.js";
-import { l as observabilityStorageCapabilitiesSchema } from "./system-6qFm79mm.js";
+import { NEW_ROUTE_DEFS, NO_OBSERVABILITY_STORAGE_CAPABILITIES, OBSERVABILITY_LIST_ENDPOINTS, OBSERVABILITY_TRACE_QUERY_TENANT_SCOPE_UPGRADE_MESSAGE, assertObservabilityDeltaSupported, assertObservabilitySpanQuerySupported, assertObservabilityThreadQuerySupported, assertObservabilityTraceAggregateSupported, assertObservabilityTraceQueryContextIdsSupported, assertObservabilityTraceQueryDiscoverySupported, assertObservabilityTraceQueryRootDurationSupported, assertObservabilityTraceQuerySupported, assertObservabilityTraceQueryTenantScopeSupported, createObservabilityListQuerySchema, getObservabilityStorageCapabilities, getObservabilityStore, isTraceQueryContextIdField, supportsObservabilityTraceQueryContextIds, supportsObservabilityTraceQueryRootDuration, supportsSpanQueryCore, supportsTraceAggregateCore, supportsTraceQueryDiscoveryCore, withDiscoveryFallback } from "./server/handlers/observability-shared.js";
+import { l as observabilityStorageCapabilitiesSchema } from "./system-BtGAJr9R.js";
 import { prepareAuthorEnrichment } from "./server/handlers/author-enrichment.js";
 import { getCallerPermissions } from "./server/handlers/authorship.js";
 import { z } from "zod/v4";
@@ -1176,6 +1176,115 @@ if (AGGREGATE_TRACES.openapi) {
 		content: { "application/json": { schema: traceQueryTimeoutErrorSchema } }
 	};
 }
+const spanQueryUnsupportedErrorSchema = z.object({
+	code: z.literal("SPAN_QUERY_UNSUPPORTED"),
+	message: z.string()
+}).strict();
+const spanQueryValidationError = (error) => ({
+	status: 422,
+	body: {
+		code: "TRACE_QUERY_INVALID",
+		message: "The span query is invalid",
+		issues: error.issues.map((issue) => ({
+			code: "invalid_request",
+			path: issue.path.map((part) => typeof part === "symbol" ? String(part) : part),
+			message: issue.message
+		}))
+	}
+});
+const QUERY_SPANS = createNewRoute(NEW_ROUTE_DEFS.QUERY_SPANS, {
+	bodySchema: coreStorage.spanQueryRequestSchema,
+	responseSchema: coreStorage.spanQueryResponseSchema,
+	onValidationError: spanQueryValidationError,
+	maxBodySize: 256 * 1024,
+	preserveHttpExceptions: true,
+	isCoreSupported: supportsSpanQueryCore,
+	onUnsupportedCore: () => throwTraceQueryError(501, {
+		code: "SPAN_QUERY_UNSUPPORTED",
+		message: "Span queries require a newer @mastra/core. Please upgrade."
+	}),
+	handler: async ({ mastra, requestContext, timeRange, where, orderBy, page }) => {
+		let plan;
+		try {
+			plan = coreStorage.planSpanQuery({
+				timeRange,
+				where,
+				orderBy,
+				page
+			}, { scope: resolveTraceQueryScope(requestContext, "SPAN_QUERY_UNSUPPORTED") });
+		} catch (error) {
+			if (error instanceof coreStorage.TraceQueryValidationError) throwTraceQueryError(422, {
+				code: error.code,
+				message: "The span query is invalid",
+				issues: error.issues
+			});
+			if (error instanceof coreStorage.TraceQueryCursorError) throwTraceQueryError(error.code === "TRACE_QUERY_CURSOR_CONFLICT" ? 409 : 400, {
+				code: error.code,
+				message: error.message
+			});
+			throw error;
+		}
+		let observabilityStore;
+		try {
+			observabilityStore = await getObservabilityStore(mastra);
+			assertObservabilitySpanQuerySupported(observabilityStore);
+			assertObservabilityTraceQueryTenantScopeSupported(observabilityStore, plan.scope);
+		} catch (error) {
+			if (error instanceof HTTPException && error.status === 501) throwTraceQueryError(501, {
+				code: "SPAN_QUERY_UNSUPPORTED",
+				message: error.message
+			});
+			throw error;
+		}
+		try {
+			return await observabilityStore.querySpans(plan);
+		} catch (error) {
+			if (error instanceof coreStorage.TraceQueryCursorError) throwTraceQueryError(error.code === "TRACE_QUERY_CURSOR_CONFLICT" ? 409 : 400, {
+				code: error.code,
+				message: error.message
+			});
+			if (error instanceof coreStorage.TraceQueryResourceLimitError) throwTraceQueryError(503, {
+				code: error.code,
+				message: error.message
+			});
+			if (error instanceof coreStorage.TraceQueryExecutionError) throwTraceQueryError(504, {
+				code: error.code,
+				message: error.message
+			});
+			throw error;
+		}
+	}
+});
+if (QUERY_SPANS.openapi) {
+	QUERY_SPANS.openapi.responses[400] = {
+		description: "Malformed JSON or malformed cursor",
+		content: { "application/json": { schema: z.union([traceQueryMalformedBodyErrorSchema, traceQueryMalformedCursorErrorSchema]) } }
+	};
+	QUERY_SPANS.openapi.responses[409] = {
+		description: "Cursor does not match the normalized query",
+		content: { "application/json": { schema: traceQueryCursorConflictErrorSchema } }
+	};
+	QUERY_SPANS.openapi.responses[413] = {
+		description: "Request body exceeds 256 KiB",
+		content: { "application/json": { schema: traceQueryBodyTooLargeErrorSchema } }
+	};
+	QUERY_SPANS.openapi.responses[422] = {
+		description: "Structurally or semantically invalid span query",
+		content: { "application/json": { schema: traceQueryValidationResponseSchema } }
+	};
+	QUERY_SPANS.openapi.responses[501] = {
+		description: "The configured observability store does not support span queries",
+		content: { "application/json": { schema: spanQueryUnsupportedErrorSchema } }
+	};
+	QUERY_SPANS.openapi.responses[503] = {
+		description: "Span query exceeded a bounded execution resource limit",
+		content: { "application/json": { schema: traceQueryResourceLimitErrorSchema } }
+	};
+	QUERY_SPANS.openapi.responses[504] = {
+		description: "Span query exceeded the configured database execution timeout",
+		content: { "application/json": { schema: traceQueryTimeoutErrorSchema } }
+	};
+}
 const GET_TRACE_QUERY_FIELDS = createNewRoute(NEW_ROUTE_DEFS.GET_TRACE_QUERY_FIELDS, {
 	bodySchema: coreStorage.getTraceQueryFieldsArgsSchema,
 	responseSchema: coreStorage.getTraceQueryFieldsResponseSchema,
@@ -1753,6 +1862,7 @@ const GET_CAPABILITIES = createRoute({
 const NEW_ROUTES = {
 	QUERY_TRACES,
 	QUERY_THREADS,
+	QUERY_SPANS,
 	LIST_LOGS,
 	LIST_SCORES,
 	CREATE_SCORE,
@@ -1786,6 +1896,6 @@ const NEW_ROUTES = {
 	GET_CAPABILITIES
 };
 //#endregion
-export { LIST_FEEDBACK as A, GET_SCORE_BREAKDOWN as C, GET_TAGS as D, GET_SERVICE_NAMES as E, QUERY_THREADS as F, QUERY_TRACES as I, UPDATE_FEEDBACK_REVIEW_STATUS as L, LIST_METRICS as M, LIST_SCORES as N, GET_TRACE_QUERY_FIELDS as O, NEW_ROUTES as P, GET_SCORE_AGGREGATE as S, GET_SCORE_TIME_SERIES as T, GET_METRIC_LABEL_VALUES as _, DELETE_SCORES as a, GET_METRIC_TIME_SERIES as b, GET_ENTITY_TYPES as c, GET_FEEDBACK_BREAKDOWN as d, GET_FEEDBACK_PERCENTILES as f, GET_METRIC_LABEL_KEYS as g, GET_METRIC_BREAKDOWN as h, DELETE_FEEDBACK as i, LIST_LOGS as j, GET_TRACE_QUERY_VALUES as k, GET_ENVIRONMENTS as l, GET_METRIC_AGGREGATE as m, CREATE_FEEDBACK as n, GET_CAPABILITIES as o, GET_FEEDBACK_TIME_SERIES as p, CREATE_SCORE as r, GET_ENTITY_NAMES as s, AGGREGATE_TRACES as t, GET_FEEDBACK_AGGREGATE as u, GET_METRIC_NAMES as v, GET_SCORE_PERCENTILES as w, GET_SCORE as x, GET_METRIC_PERCENTILES as y };
+export { LIST_FEEDBACK as A, GET_SCORE_BREAKDOWN as C, GET_TAGS as D, GET_SERVICE_NAMES as E, QUERY_SPANS as F, QUERY_THREADS as I, QUERY_TRACES as L, LIST_METRICS as M, LIST_SCORES as N, GET_TRACE_QUERY_FIELDS as O, NEW_ROUTES as P, UPDATE_FEEDBACK_REVIEW_STATUS as R, GET_SCORE_AGGREGATE as S, GET_SCORE_TIME_SERIES as T, GET_METRIC_LABEL_VALUES as _, DELETE_SCORES as a, GET_METRIC_TIME_SERIES as b, GET_ENTITY_TYPES as c, GET_FEEDBACK_BREAKDOWN as d, GET_FEEDBACK_PERCENTILES as f, GET_METRIC_LABEL_KEYS as g, GET_METRIC_BREAKDOWN as h, DELETE_FEEDBACK as i, LIST_LOGS as j, GET_TRACE_QUERY_VALUES as k, GET_ENVIRONMENTS as l, GET_METRIC_AGGREGATE as m, CREATE_FEEDBACK as n, GET_CAPABILITIES as o, GET_FEEDBACK_TIME_SERIES as p, CREATE_SCORE as r, GET_ENTITY_NAMES as s, AGGREGATE_TRACES as t, GET_FEEDBACK_AGGREGATE as u, GET_METRIC_NAMES as v, GET_SCORE_PERCENTILES as w, GET_SCORE as x, GET_METRIC_PERCENTILES as y };
 
-//# sourceMappingURL=observability-new-endpoints-lNC3o66-.js.map
+//# sourceMappingURL=observability-new-endpoints-DQuhr8aL.js.map