---
title: list_dashboard_versions
description: List a dashboard's archived body snapshots, newest first. Parameters, return shape, the empty state that carries no JSON, and scope.
updated: 2026-08-04
tools: [list_dashboard_versions]
---

Lists a dashboard's saved body snapshots, newest first. Each entry carries a
`version_id` you can pass to
[`restore_dashboard_version`](/reference/mcp-tools/restore-dashboard-version) or
[`get_dashboard_version`](/reference/mcp-tools/get-dashboard-version).

Snapshots are created automatically: each republish of an existing slug archives
the **prior** body first, so the first publish of a slug has no versions.

Behaviour hints for clients: read-only, not open-world.

## Parameters

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `slug` | string | yes | Canonical slug of the dashboard whose versions to list. |
| `workspace` | string | no | Workspace slug. |

There is no pagination and no `limit`. One call returns up to 50 versions, which
is exactly the 20 automatic plus 30 named caps added together, so the set is
always complete. See
[Version retention](/reference/mcp-tools/conventions#version-retention).

## Returns

```text
3 saved versions for "revenue-overview" (newest first):
1. "Before redesign" - 8b3f... - 2026-07-29T12:04:11Z - 47210 bytes - text/html
2. 2c91... - 2026-07-28T09:11:00Z - 46980 bytes - text/html
3. 11ad... - 2026-07-27T18:02:44Z - unknown - unknown

Pass a version_id to restore_dashboard_version to roll back. Up to 20 automatic snapshots plus your named versions (up to 30) are kept per dashboard; naming a version (update_dashboard_version) exempts it from the autosave prune.

BEGIN_JSON
{"slug":"revenue-overview","dashboard_id":"...","count":3,"versions":[{"version_id":"...","created_at":"...","size":47210,"content_type":"text/html","label":"Before redesign"}]}
END_JSON
```

A missing size or content type renders as `unknown`. The quoted prefix is the
label, omitted when a version is unnamed.

:::warning{title="The empty state carries no JSON block"}
A dashboard with no snapshots returns text only, with no `BEGIN_JSON` and no
`structuredContent`:

```text
No saved versions for "<slug>". Versions are archived automatically when you republish an existing dashboard; the first publish creates none.
```

A parser that assumes the JSON block is always present will throw here rather
than read an empty list.
:::

## Errors

The shared [slug rules](/reference/mcp-tools/conventions#paths-and-slugs), plus:

| Condition | Text |
|---|---|
| The dashboard lookup failed | `dashboard lookup failed: <err>` |
| No such dashboard | `dashboard not found` |
| The version read failed | `version list failed: <err>` |
| A workspace was named but not routed | `workspace target not resolved: this request names a workspace but was not routed to one (the caller must resolve the workspace and wire workspace-scoped deps)` |

That last one is a fail-closed guard, not something an ordinary call reaches. It
means the request said "workspace" and the scope did not follow, and refusing is
the only safe answer.

## Scope

Every member sees the whole history no matter which member published each
snapshot, because the lookup is gated on membership rather than on authorship. An
author-gated read cannot see a co-member's dashboard at all, and would report a
dashboard somebody else published as brand new.

## Check it worked

Republish an existing slug, then list again. The count should have gone up by
one and the newest entry should be the body you just replaced, not the one you
just published.