list_dashboard_versions
List a dashboard's archived body snapshots, newest first. Parameters, return shape, the empty state that carries no JSON, and scope.
Lists a dashboard's saved body snapshots, newest first. Each entry carries a
version_id you can pass to
restore_dashboard_version or
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.
Returns
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_JSONA missing size or content type renders as unknown. The quoted prefix is the
label, omitted when a version is unnamed.
The empty state carries no JSON block
A dashboard with no snapshots returns text only, with no BEGIN_JSON and no
structuredContent:
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, 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
Workspace-capable. Every member sees the whole history no matter which member published each snapshot: the lookup switches to a membership-gated read, because the personal read cannot see a co-member's dashboard at all and would otherwise report the dashboard 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.