@mastra/mcp-docs-server 1.2.19-alpha.15 → 1.2.19-alpha.18

package/.docs/models/providers.md

@@ -15,6 +15,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Abacus](https://mastra.ai/models/providers/abacus)
 - [abliteration.ai](https://mastra.ai/models/providers/abliteration-ai)
 - [AgentRouter](https://mastra.ai/models/providers/agentrouter)
+- [Agnes AI](https://mastra.ai/models/providers/agnes)
 - [AI-ROUTER](https://mastra.ai/models/providers/ai-router)
 - [ai&](https://mastra.ai/models/providers/aiand)
 - [AKI.IO](https://mastra.ai/models/providers/aki-io)
@@ -78,6 +79,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [InferX](https://mastra.ai/models/providers/inferx)
 - [Infomaniak](https://mastra.ai/models/providers/infomaniak)
 - [IO.NET](https://mastra.ai/models/providers/io-net)
+- [IteraCompute](https://mastra.ai/models/providers/iteracompute)
 - [Jalapeno Cloud](https://mastra.ai/models/providers/jalapeno)
 - [Jiekou.AI](https://mastra.ai/models/providers/jiekou)
 - [Kenari](https://mastra.ai/models/providers/kenari)
@@ -111,6 +113,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [NanoGPT](https://mastra.ai/models/providers/nano-gpt)
 - [NEAR AI Cloud](https://mastra.ai/models/providers/nearai)
 - [Nebius Token Factory](https://mastra.ai/models/providers/nebius)
+- [NeoSmith](https://mastra.ai/models/providers/neosmith)
 - [Neuralwatt](https://mastra.ai/models/providers/neuralwatt)
 - [Nova](https://mastra.ai/models/providers/nova)
 - [NovitaAI](https://mastra.ai/models/providers/novita-ai)
@@ -122,6 +125,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Opper](https://mastra.ai/models/providers/opper)
 - [OrcaRouter](https://mastra.ai/models/providers/orcarouter)
 - [OVHcloud AI Endpoints](https://mastra.ai/models/providers/ovhcloud)
+- [Pendra](https://mastra.ai/models/providers/pendra)
 - [Perplexity](https://mastra.ai/models/providers/perplexity)
 - [Perplexity Agent](https://mastra.ai/models/providers/perplexity-agent)
 - [Pioneer](https://mastra.ai/models/providers/pioneer)
@@ -143,6 +147,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [SiliconFlow (China)](https://mastra.ai/models/providers/siliconflow-cn)
 - [Snowflake Cortex](https://mastra.ai/models/providers/snowflake-cortex)
 - [STACKIT](https://mastra.ai/models/providers/stackit)
+- [Standard Compute](https://mastra.ai/models/providers/standardcompute)
 - [StepFun (China)](https://mastra.ai/models/providers/stepfun)
 - [StepFun (Global)](https://mastra.ai/models/providers/stepfun-ai)
 - [StepFun Step Plan (China)](https://mastra.ai/models/providers/stepfun-step-plan)

package/.docs/reference/cli/mastra.md

@@ -1100,9 +1100,9 @@ For runtime commands, the command resolves the target server in this order:
 2. `http://localhost:4111` for a local `mastra dev` server.
 3. `.mastra-project.json` for a Mastra platform project.
 
-Automatic platform auth is only used when the CLI resolves a Mastra platform target from `.mastra-project.json`. Localhost targets and explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
+Automatic Platform authentication is used when the CLI resolves a project from `.mastra-project.json` or recognizes an explicit Mastra-hosted Studio, Factory, or observability URL. Localhost and arbitrary explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
 
-For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets `https://observability.mastra.ai` by default instead of a project deployment URL. Trace Intelligence commands (`learning`) work the same way but target `https://output.signals.mastra.ai`. Both resolve credentials in this order:
+For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets the United States endpoint at `https://observability.mastra.ai` by default instead of a project deployment URL. Trace Intelligence commands (`learning`) work the same way but target `https://output.signals.mastra.ai`. When the CLI selects either hosted target automatically, it resolves credentials in this order:
 
 1. Explicit `Authorization` and `X-Mastra-Project-Id` headers passed with `--header`.
 2. `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from your environment.
@@ -1111,7 +1111,13 @@ For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targ
 
 Learning commands also send `X-Mastra-Organization-Id`, resolved from an explicit `--header`, `MASTRA_ORGANIZATION_ID` in your environment, or `.mastra-project.json`, in that order.
 
-Use `--url` and `--header` when you need to override the default hosted observability target or credentials.
+European Union observability data is stored at `https://observability.eu.mastra.ai`. Pass that trusted host with `--url`; it uses the same Platform credential resolution as the default United States endpoint:
+
+```bash
+mastra api --url https://observability.eu.mastra.ai trace list
+```
+
+Use `--url` and `--header` when you need to override another target or its credentials.
 
 ### Flags
 
@@ -1527,7 +1533,7 @@ mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","p
 
 #### Observability with `curl`
 
-You can call the hosted observability API directly with your platform access token and project ID:
+You can call the hosted observability API directly with your platform access token and project ID. The examples below use the United States host. Substitute `https://observability.eu.mastra.ai` for a European Union environment. The [hosted feedback query API](https://mastra.ai/docs/mastra-platform/api) documents feedback endpoints that don't have CLI commands:
 
 ```bash
 curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \

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

@@ -92,7 +92,7 @@ const scores = await mastraClient.listScoresBySpan({
 
 ## Feedback
 
-Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections. 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.
+Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the target Mastra runtime and its configured observability storage. They don't call the hosted Mastra Platform feedback query API. 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.
 
 ### Creating feedback
 

package/.docs/reference/index.md

@@ -245,6 +245,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Feedback](https://mastra.ai/reference/observability/feedback)
 - [PinoLogger](https://mastra.ai/reference/logging/pino-logger)
 - [Automatic Metrics](https://mastra.ai/reference/observability/metrics/automatic-metrics)
+- [Metric queries](https://mastra.ai/reference/observability/metrics/queries)
 - [Configuration](https://mastra.ai/reference/observability/tracing/configuration)
 - [Instances](https://mastra.ai/reference/observability/tracing/instances)
 - [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces)
@@ -295,6 +296,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.chunk()](https://mastra.ai/reference/rag/chunk)
 - [Overview](https://mastra.ai/reference/schedules/overview)
 - [createRoute()](https://mastra.ai/reference/server/create-route)
+- [Elysia Adapter](https://mastra.ai/reference/server/elysia-adapter)
 - [Express Adapter](https://mastra.ai/reference/server/express-adapter)
 - [Fastify Adapter](https://mastra.ai/reference/server/fastify-adapter)
 - [Hono Adapter](https://mastra.ai/reference/server/hono-adapter)

package/.docs/reference/observability/feedback.md

@@ -54,6 +54,8 @@ await mastra.observability.addFeedback?.({
 
 **feedback** (`FeedbackInput`): Feedback payload to add.
 
+Without `correlationContext`, the method looks up `traceId` in configured observability storage. If the trace or requested span isn't found, Mastra logs a warning and drops the feedback event. Configure `MastraStorageExporter` when adding feedback by ID after execution, including when `MastraPlatformExporter` handles remote export.
+
 ### `createFeedback(args)`
 
 Creates one feedback record through the observability storage domain. Storage-level calls write directly to the store, so include `timestamp`.
@@ -375,6 +377,8 @@ Use `FeedbackFilter` in `listFeedback()` and OLAP query `filters`.
 
 ## HTTP routes
 
+These routes belong to a Mastra runtime and use its configured observability storage. They're separate from the [unversioned Mastra Platform feedback query API](https://mastra.ai/docs/mastra-platform/api), which doesn't provide a feedback creation route.
+
 | Method | Path                                      | Purpose                      | Permission           |
 | ------ | ----------------------------------------- | ---------------------------- | -------------------- |
 | `GET`  | `/api/observability/feedback`             | List feedback records        | None derived         |

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -136,5 +136,5 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 ## Related
 
 - [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
-- [Querying metrics](https://mastra.ai/docs/observability/metrics/querying)
+- [Metric queries](https://mastra.ai/reference/observability/metrics/queries)
 - [Studio observability](https://mastra.ai/docs/studio/observability)

package/.docs/reference/observability/metrics/queries.md

@@ -0,0 +1,462 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Metric queries
+
+Metric queries read raw and aggregated metric data from the observability storage domain. For exporter and storage setup, see the [Metrics overview](https://mastra.ai/docs/observability/metrics/overview). For automatic metric names and labels, see the [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics).
+
+## Access
+
+### Observability store
+
+Use the storage domain for in-process queries:
+
+```typescript
+const observability = await mastra.getStorage()?.getStore('observability')
+
+if (!observability) {
+  throw new Error('Observability storage is not configured')
+}
+
+const result = await observability.getMetricAggregate({
+  name: ['mastra_agent_duration_ms'],
+  aggregation: 'avg',
+  filters: {
+    timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
+  },
+})
+```
+
+`getStore('observability')` returns `undefined` when the storage configuration doesn't provide the observability domain.
+
+### Client SDK
+
+`@mastra/client-js` exposes the analytics and metric discovery methods on `MastraClient`:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'http://localhost:4111',
+})
+
+const result = await client.getMetricAggregate({
+  name: ['mastra_agent_duration_ms'],
+  aggregation: 'avg',
+})
+```
+
+The client doesn't expose a raw `listMetrics()` method. Use the observability store or the `GET /api/observability/metrics` route to list raw metric records.
+
+## Shared values
+
+### Aggregations
+
+The aggregate, breakdown, and time-series methods accept these `aggregation` values:
+
+| Value            | Result                                                                                               |
+| ---------------- | ---------------------------------------------------------------------------------------------------- |
+| `sum`            | Sum of metric values                                                                                 |
+| `avg`            | Average metric value                                                                                 |
+| `min`            | Minimum metric value                                                                                 |
+| `max`            | Maximum metric value                                                                                 |
+| `count`          | Number of matching metric records                                                                    |
+| `count_distinct` | Approximate or exact number of distinct values in `distinctColumn`, depending on the storage backend |
+| `last`           | Most recent matching metric value                                                                    |
+
+When `aggregation` is `count_distinct`, `distinctColumn` is required. Supported columns are:
+
+```text
+entityType
+entityName
+parentEntityType
+parentEntityName
+rootEntityType
+rootEntityName
+name
+provider
+model
+environment
+executionSource
+serviceName
+threadId
+resourceId
+```
+
+### Intervals
+
+Time-series and percentile queries accept `1m`, `5m`, `15m`, `1h`, or `1d`.
+
+### Filters
+
+All metric operations accept the same optional `filters` object. Raw list requests pass these fields as query parameters. Analytics methods pass them in the JSON request body.
+
+| Field                   | Type                                                                             | Description                                                                                                                        |
+| ----------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `timestamp`             | `{ start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }` | Timestamp range. Boundaries are inclusive unless their corresponding exclusive flag is `true`. HTTP requests use ISO date strings. |
+| `traceId`               | `string`                                                                         | Exact trace ID                                                                                                                     |
+| `traceIds`              | `string[]`                                                                       | One to 1,000 trace IDs                                                                                                             |
+| `spanId`                | `string`                                                                         | Exact span ID                                                                                                                      |
+| `entityType`            | `EntityType`                                                                     | Entity type                                                                                                                        |
+| `entityName`            | `string`                                                                         | Entity name                                                                                                                        |
+| `entityVersionId`       | `string`                                                                         | Entity version ID                                                                                                                  |
+| `parentEntityType`      | `EntityType`                                                                     | Parent entity type                                                                                                                 |
+| `parentEntityName`      | `string`                                                                         | Parent entity name                                                                                                                 |
+| `parentEntityVersionId` | `string`                                                                         | Parent entity version ID                                                                                                           |
+| `rootEntityType`        | `EntityType`                                                                     | Root entity type                                                                                                                   |
+| `rootEntityName`        | `string`                                                                         | Root entity name                                                                                                                   |
+| `rootEntityVersionId`   | `string`                                                                         | Root entity version ID                                                                                                             |
+| `userId`                | `string`                                                                         | User ID                                                                                                                            |
+| `organizationId`        | `string`                                                                         | Organization ID                                                                                                                    |
+| `experimentId`          | `string`                                                                         | Experiment or evaluation run ID                                                                                                    |
+| `serviceName`           | `string`                                                                         | Service name                                                                                                                       |
+| `environment`           | `string`                                                                         | Environment name                                                                                                                   |
+| `resourceId`            | `string`                                                                         | Resource ID                                                                                                                        |
+| `runId`                 | `string`                                                                         | Run ID                                                                                                                             |
+| `sessionId`             | `string`                                                                         | Session ID                                                                                                                         |
+| `threadId`              | `string`                                                                         | Thread ID                                                                                                                          |
+| `requestId`             | `string`                                                                         | Request ID                                                                                                                         |
+| `executionSource`       | `string`                                                                         | Execution source                                                                                                                   |
+| `tags`                  | `string[]`                                                                       | Records must contain all specified tags                                                                                            |
+| `name`                  | `string[]`                                                                       | One or more metric names                                                                                                           |
+| `provider`              | `string`                                                                         | Model provider                                                                                                                     |
+| `model`                 | `string`                                                                         | Model ID                                                                                                                           |
+| `costUnit`              | `string`                                                                         | Cost unit                                                                                                                          |
+| `labels`                | `Record<string, string>`                                                         | Exact matches for all specified metric label key-value pairs                                                                       |
+| `source`                | `string`                                                                         | Deprecated. Use `executionSource`.                                                                                                 |
+
+## Analytics methods
+
+### `getMetricAggregate(args)`
+
+Returns one value across all matching records. The observability store and `MastraClient` expose this method.
+
+#### Arguments
+
+| Field            | Type                                                     | Required             | Description                                                                                |
+| ---------------- | -------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------ |
+| `name`           | `string[]`                                               | Yes                  | One or more metric names                                                                   |
+| `aggregation`    | `AggregationType`                                        | Yes                  | Aggregation to apply                                                                       |
+| `distinctColumn` | `MetricDistinctColumn`                                   | For `count_distinct` | Column whose distinct values are counted                                                   |
+| `filters`        | `MetricsFilter`                                          | No                   | Shared metric filters                                                                      |
+| `comparePeriod`  | `'previous_period' \| 'previous_day' \| 'previous_week'` | No                   | Adds comparison-period values. `previous_period` uses the duration of `filters.timestamp`. |
+
+#### Returns
+
+```typescript
+{
+  value: number | null
+  previousValue?: number | null
+  changePercent?: number | null
+  estimatedCost?: number | null
+  costUnit?: string | null
+  previousEstimatedCost?: number | null
+  costChangePercent?: number | null
+}
+```
+
+`costUnit` is `null` when the matching records don't have one shared unit. Cost fields are optional and may be `null` when the records don't include cost context.
+
+```typescript
+const result = await observability.getMetricAggregate({
+  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
+  aggregation: 'sum',
+  filters: {
+    timestamp: {
+      start: new Date('2026-08-24T00:00:00Z'),
+      end: new Date('2026-08-25T00:00:00Z'),
+    },
+  },
+  comparePeriod: 'previous_period',
+})
+```
+
+**HTTP:** `POST /api/observability/metrics/aggregate`
+
+### `getMetricBreakdown(args)`
+
+Groups matching records by one or more dimensions and aggregates each group. The observability store and `MastraClient` expose this method.
+
+#### Arguments
+
+| Field            | Type                   | Required             | Description                                                                         |
+| ---------------- | ---------------------- | -------------------- | ----------------------------------------------------------------------------------- |
+| `name`           | `string[]`             | Yes                  | One or more metric names                                                            |
+| `groupBy`        | `string[]`             | Yes                  | One or more fields to group by                                                      |
+| `aggregation`    | `AggregationType`      | Yes                  | Aggregation for each group                                                          |
+| `distinctColumn` | `MetricDistinctColumn` | For `count_distinct` | Column whose distinct values are counted                                            |
+| `filters`        | `MetricsFilter`        | No                   | Shared metric filters                                                               |
+| `limit`          | `number`               | No                   | Positive integer up to 1,000. Required for high-cardinality groupings.              |
+| `orderDirection` | `'ASC' \| 'DESC'`      | No                   | Sort direction for the aggregated value. Storage implementations default to `DESC`. |
+
+#### Returns
+
+```typescript
+{
+  groups: Array<{
+    dimensions: Record<string, string | null>
+    value: number
+    estimatedCost?: number | null
+    costUnit?: string | null
+  }>
+}
+```
+
+```typescript
+const result = await client.getMetricBreakdown({
+  name: ['mastra_model_total_input_tokens'],
+  groupBy: ['entityName'],
+  aggregation: 'sum',
+  limit: 10,
+  orderDirection: 'DESC',
+})
+```
+
+**HTTP:** `POST /api/observability/metrics/breakdown`
+
+### `getMetricTimeSeries(args)`
+
+Buckets matching values by time interval, with optional grouping. The observability store and `MastraClient` expose this method.
+
+#### Arguments
+
+| Field            | Type                   | Required             | Description                                 |
+| ---------------- | ---------------------- | -------------------- | ------------------------------------------- |
+| `name`           | `string[]`             | Yes                  | One or more metric names                    |
+| `interval`       | `AggregationInterval`  | Yes                  | Time bucket interval                        |
+| `aggregation`    | `AggregationType`      | Yes                  | Aggregation for each bucket                 |
+| `distinctColumn` | `MetricDistinctColumn` | For `count_distinct` | Column whose distinct values are counted    |
+| `filters`        | `MetricsFilter`        | No                   | Shared metric filters                       |
+| `groupBy`        | `string[]`             | No                   | Fields used to split the result into series |
+
+#### Returns
+
+```typescript
+{
+  series: Array<{
+    name: string
+    costUnit?: string | null
+    points: Array<{
+      timestamp: Date
+      value: number
+      estimatedCost?: number | null
+    }>
+  }>
+}
+```
+
+```typescript
+const result = await client.getMetricTimeSeries({
+  name: ['mastra_model_total_input_tokens'],
+  interval: '1h',
+  aggregation: 'sum',
+  filters: {
+    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
+  },
+})
+```
+
+**HTTP:** `POST /api/observability/metrics/timeseries`
+
+### `getMetricPercentiles(args)`
+
+Calculates percentile values in time buckets. The observability store and `MastraClient` expose this method.
+
+#### Arguments
+
+| Field         | Type                  | Required | Description                             |
+| ------------- | --------------------- | -------- | --------------------------------------- |
+| `name`        | `string`              | Yes      | One metric name                         |
+| `percentiles` | `number[]`            | Yes      | One or more values from `0` through `1` |
+| `interval`    | `AggregationInterval` | Yes      | Time bucket interval                    |
+| `filters`     | `MetricsFilter`       | No       | Shared metric filters                   |
+
+#### Returns
+
+```typescript
+{
+  series: Array<{
+    percentile: number
+    points: Array<{
+      timestamp: Date
+      value: number
+    }>
+  }>
+}
+```
+
+```typescript
+const result = await client.getMetricPercentiles({
+  name: 'mastra_agent_duration_ms',
+  percentiles: [0.5, 0.95, 0.99],
+  interval: '1h',
+})
+```
+
+**HTTP:** `POST /api/observability/metrics/percentiles`
+
+## Raw metric records
+
+### `listMetrics(args)`
+
+Returns stored metric observations without aggregating them. This method is available on the observability store. The HTTP route accepts the same fields as query parameters.
+
+#### Arguments
+
+Page mode is the default:
+
+```typescript
+{
+  mode?: 'page'
+  filters?: MetricsFilter
+  pagination?: {
+    page?: number // Default: 0
+    perPage?: number // Default: 10; maximum: 100
+  }
+  orderBy?: {
+    field?: 'timestamp' // Default: 'timestamp'
+    direction?: 'ASC' | 'DESC' // Default: 'DESC'
+  }
+}
+```
+
+Delta mode supports incremental polling:
+
+```typescript
+{
+  mode: 'delta'
+  filters?: MetricsFilter
+  after?: string
+  limit?: number // Default: 10; maximum: 100
+}
+```
+
+`pagination` and `orderBy` aren't allowed in delta mode. `after` and `limit` aren't allowed in page mode. A backend that doesn't support delta polling returns an unsupported-operation error.
+
+#### Returns
+
+```typescript
+{
+  metrics: MetricRecord[]
+  pagination?: {
+    total: number
+    page: number
+    perPage: number | false
+    hasMore: boolean
+  }
+  delta?: {
+    limit: number
+    hasMore: boolean
+  }
+  deltaCursor?: string
+}
+```
+
+A `MetricRecord` has this shape:
+
+```typescript
+{
+  metricId?: string | null
+  timestamp: Date
+  name: string
+  value: number
+  traceId?: string | null
+  spanId?: string | null
+  entityType?: EntityType | null
+  entityId?: string | null
+  entityName?: string | null
+  parentEntityType?: EntityType | null
+  parentEntityId?: string | null
+  parentEntityName?: string | null
+  rootEntityType?: EntityType | null
+  rootEntityId?: string | null
+  rootEntityName?: string | null
+  userId?: string | null
+  organizationId?: string | null
+  resourceId?: string | null
+  runId?: string | null
+  sessionId?: string | null
+  threadId?: string | null
+  requestId?: string | null
+  environment?: string | null
+  serviceName?: string | null
+  scope?: Record<string, unknown> | null
+  entityVersionId?: string | null
+  parentEntityVersionId?: string | null
+  rootEntityVersionId?: string | null
+  experimentId?: string | null
+  executionSource?: string | null
+  tags?: string[] | null
+  source?: string | null // Deprecated
+  provider?: string | null
+  model?: string | null
+  estimatedCost?: number | null
+  costUnit?: string | null
+  costMetadata?: Record<string, unknown> | null
+  labels: Record<string, string>
+  metadata?: Record<string, unknown> | null
+}
+```
+
+**HTTP:** `GET /api/observability/metrics`
+
+## Metric discovery
+
+The observability store and `MastraClient` expose the metric discovery methods. HTTP requests pass arguments as query parameters.
+
+| Method                       | Arguments                                                                   | Returns                | HTTP route                                             |
+| ---------------------------- | --------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------ |
+| `getMetricNames(args?)`      | `{ prefix?: string; limit?: number }`                                       | `{ names: string[] }`  | `GET /api/observability/discovery/metric-names`        |
+| `getMetricLabelKeys(args)`   | `{ metricName: string }`                                                    | `{ keys: string[] }`   | `GET /api/observability/discovery/metric-label-keys`   |
+| `getMetricLabelValues(args)` | `{ metricName: string; labelKey: string; prefix?: string; limit?: number }` | `{ values: string[] }` | `GET /api/observability/discovery/metric-label-values` |
+
+`limit` must be a positive integer when provided.
+
+```typescript
+const { names } = await client.getMetricNames({ prefix: 'mastra_model_' })
+const { keys } = await client.getMetricLabelKeys({ metricName: names[0] })
+const { values } = await client.getMetricLabelValues({
+  metricName: names[0],
+  labelKey: keys[0],
+  limit: 20,
+})
+```
+
+The observability discovery API also exposes shared dimensions used by traces, logs, and metrics:
+
+| Store or client method  | Arguments                                 | HTTP route                                       |
+| ----------------------- | ----------------------------------------- | ------------------------------------------------ |
+| `getEntityTypes()`      | None in `MastraClient`; `{}` in the store | `GET /api/observability/discovery/entity-types`  |
+| `getEntityNames(args?)` | `{ entityType?: EntityType }`             | `GET /api/observability/discovery/entity-names`  |
+| `getServiceNames()`     | None in `MastraClient`; `{}` in the store | `GET /api/observability/discovery/service-names` |
+| `getEnvironments()`     | None in `MastraClient`; `{}` in the store | `GET /api/observability/discovery/environments`  |
+| `getTags(args?)`        | `{ entityType?: EntityType }`             | `GET /api/observability/discovery/tags`          |
+
+## HTTP routes
+
+| Method | Route                                              | Input            |
+| ------ | -------------------------------------------------- | ---------------- |
+| `GET`  | `/api/observability/metrics`                       | Query parameters |
+| `POST` | `/api/observability/metrics/aggregate`             | JSON body        |
+| `POST` | `/api/observability/metrics/breakdown`             | JSON body        |
+| `POST` | `/api/observability/metrics/timeseries`            | JSON body        |
+| `POST` | `/api/observability/metrics/percentiles`           | JSON body        |
+| `GET`  | `/api/observability/discovery/metric-names`        | Query parameters |
+| `GET`  | `/api/observability/discovery/metric-label-keys`   | Query parameters |
+| `GET`  | `/api/observability/discovery/metric-label-values` | Query parameters |
+| `GET`  | `/api/observability/discovery/entity-types`        | None             |
+| `GET`  | `/api/observability/discovery/entity-names`        | Query parameters |
+| `GET`  | `/api/observability/discovery/service-names`       | None             |
+| `GET`  | `/api/observability/discovery/environments`        | None             |
+| `GET`  | `/api/observability/discovery/tags`                | Query parameters |
+
+All routes require a configured observability domain. The aggregate, breakdown, time-series, and percentile routes require the `observability:read` permission when runtime authorization is enabled.
+
+## Unsupported backends
+
+The base observability storage implementation throws `*_NOT_IMPLEMENTED` errors for raw listing, analytics, and discovery methods. A configured observability domain can therefore exist while its backend doesn't implement metric queries.
+
+DuckDB, ClickHouse, Postgres v-next observability storage, and in-memory observability storage implement metric queries. Google Cloud Spanner implements them only when `disableMetrics` is `false`. Metrics are disabled by default. Other storage adapters may support tracing without supporting metrics.
+
+## CLI
+
+The `mastra api metric` commands cover aggregate, breakdown, time-series, percentile, metric-name, label-key, and label-value queries. See the [`mastra api metric` CLI reference](https://mastra.ai/reference/cli/mastra) for commands, targeting, authentication, and schema inspection.