---
title: "POST /api/agent/v1/metric"
method: POST
path: "/api/agent/v1/metric"
tags: ["/api/agent"]
---

# POST /api/agent/v1/metric

`POST /api/agent/v1/metric`

## Request

- Base URL: `` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/agent/v1/metric`
- Auth: API key in header `X-API-Key`

Save a previously constructed query as a named metric.

  A metric is a reusable aggregation (a `Card` of type `metric`): the underlying query must have
  exactly one aggregation and at most one date/datetime grouping. The `query` parameter accepts a
  `query_handle` (UUID) returned by `construct_query`, or a base64-encoded MBQL string. MCP callers
  should always use the handle.
  Optionally specify display type, description, collection, and visualization settings.
  If `collection_id` is omitted the metric is saved to the caller's personal collection.
  Pass an explicit `null` to save it to the root collection.
  The response `collection_path` is the saved location.

## Request body

- MetabaseAgentApiApiCreateMetricRequest
  - `collection_id` integer, nullable: value must be an integer greater than zero.
  - `description` string, nullable
  - `display` 'table' | 'bar' | 'line' | 'pie' | 'scatter' | 'area' | 'row' | 'combo' | 'pivot' | 'scalar' | 'smartscalar' | 'gauge' | 'progress' | 'funnel' | 'map' | 'waterfall' | 'sankey': Display types accepted by Card. Validates LLM-passed values so a bogus value (e.g. `"potato"`) gets a 400 rather than persisting junk.
  - `name` string, required: value must be a non-blank string.
  - `query` string, required: value must be a non-blank string.
  - `visualization_settings` object, nullable: Value must be a map.

## Response `2XX`

Successful response

- MetabaseAgentApiApiCreateMetricResponse
  - `collection_id` integer, nullable, required: value must be an integer greater than zero.
  - `collection_path` string, required
  - `description` string, nullable, required
  - `display` string, required
  - `id` integer, required: value must be an integer greater than zero.
  - `name` string, required: value must be a non-blank string.
  - `url` string, required

## Other responses

- `4XX`: Client error response
- `5XX`: Server error response

## Changes

- **2026-11-04** `2e178f5a7934`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/metabase/apis/metabase-api/changes/api/agent/v1/metric/post.md)

---

[API](https://skmtc.dev/metabase/apis/metabase-api.md) - [All operations](https://skmtc.dev/metabase/apis/metabase-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metabase/apis/metabase-api/revisions/2e178f5a7934?raw)