> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `brain` CLI; `brain --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces.

# Retire metrics

> Withdraw a release, name a replacement, or archive a metric in Metrics Studio so agents stop getting it and history stays.

<Badge color="orange">Preview</Badge>

Retiring a metric takes it out of what agents read while keeping its revisions and release history. Use it when a metric is a duplicate, wrong, or replaced by a better one. This guide shows you how to withdraw a release, name a replacement so users know where to go, archive the metric, and bring it back if you need to.

Withdrawing and archiving differ. Withdrawing takes back one release, and agents that search still find the metric itself. Archiving retires its releases and removes the metric from the list and search.

## Before you begin

Before you start, make sure you have:

* **Access**: Access to Metrics Studio and permission to release and archive metrics in the workspace.
* **Metric to retire**: The metric, and its replacement if it has one. See [Find and read metrics](/studios/metrics/how-tos/find-and-read-metrics) to check which metrics use it.
* **Metric app**: An administrator has installed the Metric app in your account.

<Steps>
  <Step title="Withdraw release (optional)">
    Use this to take back one release and keep the metric. Open **More actions** and choose the withdraw action, headed **Withdraw a release**. Withdrawing takes a release back for good.

    Pick the **Release to withdraw**, which defaults to the live one, and give a **Reason for withdrawal** (required, up to 4,000 characters). The dialog says what the channel serves afterwards: either the previous version is live again, or nothing is live until you release a revision. Choose **Withdraw {label}**.

    "There is no eligible release to withdraw." means there is nothing live or pending to take back.
  </Step>

  <Step title="Name replacement">
    Tell users where to go before you archive. Open the metric's **Dependencies** tab and choose **Name a replacement**. Choose the **Replacement metric**, an active metric in the same workspace, review **What uses it**, and tick "I checked this replacement and what uses it." Then choose **Save replacement**.

    This saves a new revision that names the replacement. It releases neither metric and withdraws nothing, and agents still get the old metric until it is archived. The catalog shows **Replaced by {name}** on it.

    <Warning>
      The list under **What uses it** shows recorded links only. Metrics you cannot see, archived ones, and SQL that mentions a metric without naming it can be missing, so an empty list does not prove nothing uses it. If you see "The save could not be confirmed. Do not repeat it: reload, and check History to see whether it went through.", do not save again.
    </Warning>
  </Step>

  <Step title="Archive metric">
    Open **More actions** and choose **Archive**. The dialog lists what archiving does: "Agents stop getting it", it "leaves the metrics list and search", and "Its revisions and release history stay, and Restore brings it back as a new revision." It also lists what is linked to the metric. If no replacement is named, it links to **Name a replacement before archiving**. Studio shows the archive button in red. Confirm it.

    The result reads "Archived. History is preserved."

    <Warning>
      Studio refuses to archive a held metric: "Registry refuses archive while the scan gate is blocked. Archiving cannot hide that verdict."
    </Warning>
  </Step>

  <Step title="Restore metric (optional)">
    To bring an archived metric back, open it and choose **Restore as a new revision**. It brings the metric back as a new revision, keeps its history, and releases nothing, so nothing reaches agents until you release it. See [Release metrics](/studios/metrics/how-tos/release-metrics).
  </Step>

  <Step title="Verify retirement">
    Open the catalog and choose the **Archived** view. Confirm the metric is listed, and that **Release** shows **Archived** with the hint "Its releases are retired". Open its **History** and confirm that withdrawn versions are tagged **Withdrawn** and that the reason is shown.
  </Step>
</Steps>

## Next steps

* [Find and read metrics](/studios/metrics/how-tos/find-and-read-metrics): Confirm what agents get after retiring a metric.

## See also

* [Release metrics](/studios/metrics/how-tos/release-metrics): Release the replacement.
* [Metrics Studio](/studios/metrics-studio): How revisions, releases, and withdrawal relate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.