---
title: "PUT /api/agent/v1/metric/{id}"
method: PUT
path: "/api/agent/v1/metric/{id}"
tags: ["/api/agent"]
---

# PUT /api/agent/v1/metric/{id}

`PUT /api/agent/v1/metric/{id}`

## Request

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

Update a saved metric. Patch semantics - only fields that you pass are changed.

  Set `collection_id` to move the metric to a different collection. Set `archived: true` to archive.
  Archiving is a soft delete - there is no delete endpoint. It can be reversed by setting
  `archived: false`.
  Pass `query` (a query_handle from construct_query, or a base64 MBQL string) to replace the underlying
  query; the replacement must still be a valid metric (exactly one aggregation, at most one
  date/datetime grouping). The target card must be a metric — use `update_question` for questions.

## Path parameters

- `id` integer, required

## Request body

- MetabaseAgentApiApiUpdateMetricRequest: Patch shape for `update_metric`. Every field is optional; only the fields the caller passes are changed. `:query` accepts a base64-encoded MBQL string (or query_handle UUID resolved upstream in the MCP layer) and must still describe a valid metric.
  - `archived` boolean, nullable
  - `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, nullable: value must be a non-blank string.
  - `query` string, nullable: value must be a non-blank string.
  - `visualization_settings` object, nullable: Value must be a map.

## Response `2XX`

Successful response

- MetabaseAgentApiApiUpdateMetricResponse: Returned by `update_metric` - the fields the LLM is most likely to want to read back after an update. Excludes the full dataset_query, which the caller can re-fetch via `read_resource` if needed.
  - `archived` boolean, required
  - `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.

## 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/:id/put.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)