---
title: delete_dashboard
description: Retire a dashboard by its canonical slug. Parameters, the deletion ordering, the degraded return variants, errors and scope.
updated: 2026-08-27
tools: [delete_dashboard]
---

Retires a dashboard. Its URL stops resolving, the dashboard leaves the
app, and the stored bytes are removed. The database row is preserved internally
so the deletion can be audited or reversed out of band; **do not offer this as
end-user undo**. Deleting a slug frees that name for a fresh publish.

To roll a body back to an earlier snapshot without retiring the dashboard, use
[`restore_dashboard_version`](/reference/mcp-tools/restore-dashboard-version)
instead.

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

## Parameters

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `slug` | string | yes | The **canonical** slug. Aliases left by earlier renames are rejected. |

There is no `workspace` argument. A workspace-authorized connection deletes that
workspace's dashboards.

## Returns

```text
Deleted dashboard for the acme workspace.
Slug: revenue-overview
URL https://acme.dashies.ai/revenue-overview now 404s.
Aliases tombstoned: 1
R2 objects removed: 1 (dashboard body) + 2 (data, cube and thumbnail objects)
Version snapshots purged: 7
```

Deletion runs database-first, then best-effort cleanup: soft-delete the row,
purge versions, delete the stored prefix, then garbage-collect per-version
objects. A cleanup step that does not finish replaces its line rather than
failing the call.

A failure to remove the canonical body pushes **two** lines, not one. The count
still appears, because a failure is exactly when you need to know what did get
removed:

```text
Note: R2 cleanup didn't finish - some object bytes may linger (not user-visible). Error: <err>
R2 objects removed: 2 (data, cube and thumbnail objects)
```

Note the shape: on that branch the line has ONE term rather than the two the clean
receipt shows, because the body is the half that failed.

A failed version purge replaces its count line:

```text
Version snapshots: purge failed (rows may remain, swept later). Error: <err>
```

And a delete whose row lookup returns no usable id skips the id-keyed cleanup
entirely and says so, in addition to the lines above:

```text
Note: the data/cube/thumbnail cleanup was skipped because the delete returned no usable dashboard id - those objects are orphaned and need a manual sweep.
```

Both of those mean the dashboard **is** deleted and its URL **does** 404. What
lingers is invisible storage that a later sweep collects.

## Errors

The shared [slug rules](/reference/mcp-tools/conventions#paths-and-slugs), plus the
database's own refusal, passed through unchanged:

```text
delete rejected: <msg>
```

**That wrapper carries more than one refusal, and the recovery differs.** Pass an
alias rather than the canonical slug and the message names the current canonical
slug, so re-issue the call with it. Pass a slug that names no dashboard and the
message is `dashboard not found for slug "<slug>"`, the same sentence
[`update_dashboard`](/reference/mcp-tools/update-dashboard) gives, and there is
nothing to retry.

## Scope

A dashboard's stored objects live under a workspace-scoped prefix, and the receipt labels the target
`the <workspace> workspace`.

## Check it worked

Load the URL the receipt printed. It should return 404. Then run
[`list_dashboards`](/reference/mcp-tools/list-dashboards) and confirm the slug is
gone, since the list excludes soft-deleted rows.