@mastra/server 1.75.0-alpha.3 → 1.75.0-alpha.5

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.3"
+  version: "1.75.0-alpha.5"
 ---
 
 ## 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.3",
+  "version": "1.75.0-alpha.5",
   "package": "@mastra/server",
   "exports": {},
   "modules": {}

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

@@ -6,13 +6,74 @@
 
 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 through storage
+## 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)`. It returns individual completed spans across traces, including matching child spans. Check `storage.getFeatures()?.includes('span-query')` before using this optional storage method. Server routes and client SDK support are separate from this storage API.
+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:
 
@@ -768,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