mastra 1.34.1-alpha.2 → 1.34.1-alpha.3

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra
 description: Documentation for mastra. Use when working with mastra APIs, configuration, or implementation.
 metadata:
   package: "mastra"
-  version: "1.34.1-alpha.2"
+  version: "1.34.1-alpha.3"
 ---
 
 ## When to use
@@ -16,7 +16,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [API Reference: Mastra platform](references/docs-mastra-platform-api.md) - Use the Mastra platform REST API to manage members, tokens, Studio and Server deployments, gateways, observability feedback, and project-scoped resources.
+- [API Reference: Mastra platform](references/docs-mastra-platform-api.md) - Use the Mastra platform REST API to manage members, tokens, Studio and Server deployments, gateways, observability feedback and metrics, and project-scoped resources.
 - [Observability](references/docs-mastra-platform-observability.md) - Collect, import, and query hosted traces, logs, metrics, scores, and feedback from Mastra applications with Mastra Platform Observability and local fallback storage.
 
 ### Reference

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.34.1-alpha.2",
+  "version": "1.34.1-alpha.3",
   "package": "mastra",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-mastra-platform-api.md

@@ -179,6 +179,94 @@ The API returns `401` for invalid credentials, `403` for organization authorizat
 
 Hosted observability doesn't provide a feedback creation route. Export feedback from the application as described in [Export feedback to Mastra Platform](https://mastra.ai/docs/observability/feedback).
 
+## Metrics API
+
+The Metrics API queries metrics exported to Mastra Platform Observability. Because the API is unversioned, backwards compatibility isn't guaranteed. Rate limits, retention, and ingestion-to-query freshness aren't published contracts.
+
+The endpoints share their query parameters, request bodies, and response types with the Mastra runtime metric routes. See the [metric queries reference](https://mastra.ai/reference/observability/metrics/queries) for the full contract, including [shared filters](https://mastra.ai/reference/observability/metrics/queries), [analytics methods](https://mastra.ai/reference/observability/metrics/queries), and [metric discovery](https://mastra.ai/reference/observability/metrics/queries).
+
+Use the root URL for your environment's data-residency region:
+
+| Region         | Root URL                                               |
+| -------------- | ------------------------------------------------------ |
+| United States  | `https://observability.mastra.ai/api/observability`    |
+| European Union | `https://observability.eu.mastra.ai/api/observability` |
+
+Telemetry stays in its residency region. Querying the other region returns no records for the environment. See [Observability co-location](https://mastra.ai/docs/mastra-platform/regions) for the environment-to-region mapping.
+
+### Authentication and project scope
+
+Every request requires a platform access token. Create one in [Mastra Platform](https://projects.mastra.ai), or use the token written to `.env` during Platform setup.
+
+Include `X-Mastra-Project-Id` to limit results to one project. If you omit it, the query covers metrics in every project available to the token's organization.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/discovery/metric-names?prefix=mastra_model_" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
+Use an organization-scoped Platform access token. Gateway inference keys such as `mk_*` keys aren't accepted. Queries remain constrained to the token's organization even when you supply a project ID.
+
+### Endpoints
+
+| Method | Endpoint                         | Description                             |
+| ------ | -------------------------------- | --------------------------------------- |
+| GET    | `/metrics`                       | List raw metric records                 |
+| POST   | `/metrics/aggregate`             | Return one aggregate value              |
+| POST   | `/metrics/breakdown`             | Group metrics by dimensions             |
+| POST   | `/metrics/timeseries`            | Bucket metrics by interval              |
+| POST   | `/metrics/percentiles`           | Return percentile series for one metric |
+| GET    | `/discovery/metric-names`        | List metric names                       |
+| GET    | `/discovery/metric-label-keys`   | List label keys for a metric            |
+| GET    | `/discovery/metric-label-values` | List values for a metric label key      |
+
+The list and discovery endpoints take their arguments as query parameters. See [`listMetrics(args)`](https://mastra.ai/reference/observability/metrics/queries) and [metric discovery](https://mastra.ai/reference/observability/metrics/queries) in the metric queries reference for the parameters each one accepts.
+
+Analytics endpoints accept the same JSON request bodies and return types as the [metric queries reference](https://mastra.ai/reference/observability/metrics/queries), including `name`, `aggregation`, `filters`, `groupBy`, `interval`, `percentiles`, `comparePeriod`, `limit`, `orderDirection`, and `distinctColumn`.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/metrics/aggregate" \
+  -X POST \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
+  -H "Content-Type: application/json" \
+  --data '{"name":["mastra_model_total_input_tokens","mastra_model_total_output_tokens"],"aggregation":"sum","filters":{"timestamp":{"start":"2026-09-13T00:00:00Z","end":"2026-10-13T00:00:00Z"}},"comparePeriod":"previous_period"}' | jq
+```
+
+`filters.timestamp` is optional. If you omit `start` and `end`, the query covers all retained data. `comparePeriod` requires both `start` and `end`. Without them, the previous-period fields are `null`.
+
+The API returns `401` for invalid credentials, `403` for organization authorization failures, and `400` for malformed query arguments or JSON bodies.
+
+#### `MastraClient`
+
+`MastraClient` from `@mastra/client-js` exposes the analytics and discovery methods. Set `baseUrl` to the region's host without the `/api/observability` path:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const mastraClient = new MastraClient({
+  baseUrl: 'https://observability.mastra.ai',
+  headers: {
+    Authorization: `Bearer ${process.env.MASTRA_PLATFORM_ACCESS_TOKEN}`,
+    'X-Mastra-Project-Id': process.env.MASTRA_PROJECT_ID!,
+  },
+})
+
+const result = await mastraClient.getMetricAggregate({
+  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
+  aggregation: 'sum',
+})
+```
+
+#### CLI
+
+The [`mastra api metric`](https://mastra.ai/reference/cli/mastra) commands target the United States endpoint by default. Pass `--url` to query the European Union region:
+
+```bash
+mastra api --url https://observability.eu.mastra.ai metric aggregate '<json>'
+```
+
 ## Gateway proxy endpoints
 
 Visit the [Gateway documentation](https://gateway.mastra.ai/docs) for more details.

package/dist/docs/references/docs-mastra-platform-observability.md

@@ -168,6 +168,8 @@ The CLI can infer platform credentials from your project environment. See the [`
 
 You can query exported feedback over HTTP. See the [Feedback API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, project scoping, and supported query parameters such as `traceId` and `environment`.
 
+You can query exported metrics over HTTP, with `MastraClient`, or with `mastra api metric`. See the [Metrics API](https://mastra.ai/docs/mastra-platform/api) for regional endpoints, authentication, project scoping, and supported endpoints.
+
 ## Import existing traces
 
 Use `mastra traces import` to move existing trace history from a supported observability provider into an existing Mastra Platform project. The command reads and validates complete traces at the source, converts them into Mastra spans, then uses a shared workflow for preparation, upload, resume, and verification.