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

# Dashboards & sharing

> Build Explorer visuals and dashboards from your queries, then publish share and embed links.

<Info>
  Visuals and dashboards both read from **saved** Explorer queries. Create the query first with `create_explorer_query`: an ephemeral `run_sql_query` result can't back a chart. See [SQL & queries](/ai/mcp/tools-reference/sql-and-queries).
</Info>

## Available tools

| Tool | Description |
| :- | :- |
| `create_explorer_visual` | Attach a visual to a saved query, or replace one in place |
| `get_explorer_visual` | Read a visual's full spec |
| `delete_explorer_visual` | Delete a visual |
| `read_dashboard` | Inspect a dashboard at any depth |
| `set_dashboard` | Create, update, or delete any node in a dashboard tree |
| `delete_dashboard` | Delete a whole dashboard |
| `share_explorer_query` | Publish a query or visual, returning share and embed links |
| `share_dashboard` | Publish a dashboard, returning a share link |

<Warning>
  Fetch the relevant skill before you construct a spec. Both `set_dashboard` and `create_explorer_visual` take a typed JSON config, and the exact schema per type lives in the skill. See [Skills](/ai/mcp/tools-reference/skills).
</Warning>

## Visuals

A visual belongs to a query. `spec.type` selects the variant, and the remaining fields depend on that type.

**Types:** `chart`, `value`, `table`, `pie`, `sankey`, `treemap`, `scatter`, `map`, `chord`.

<Steps>
  <Step title="Load the schema">
    Call `get_skill(name="explorer-visuals")` for general guidance, then `get_skill(name="explorer-visuals", reference_title="<type>")` for that type's exact JSON schema.
  </Step>

  <Step title="Create the visual">
    ```json theme={null}
    {
      "name": "create_explorer_visual",
      "arguments": {
        "query_id": "<QUERY_ID>",
        "title": "Daily DEX volume",
        "subtitle": "Last 90 days, all chains",
        "spec": { "type": "chart" }
      }
    }
    ```

    `create_explorer_visual` returns a `visual_id` and the visual's URL. Pass an existing `visual_id` to replace that visual in place, and omit it to add a new one.
  </Step>
</Steps>

`get_explorer_query` returns a query's `visuals` list. Use those IDs with `get_explorer_visual`, `delete_explorer_visual`, or the `visual_id` argument of `share_explorer_query`.

<Note>
  Editing a visual requires edit access to its parent query.
</Note>

## Dashboards

A dashboard is a tree: **dashboard > page > section > element**. `set_dashboard` upserts or deletes any node in that tree, and the ID path you pass locates the target.

| IDs you pass | Effect |
| :- | :- |
| No `dashboard_id` | Create a new dashboard |
| `dashboard_id` only, `spec.kind: "dashboard"` | Update that dashboard |
| `dashboard_id`, `spec.kind: "page"` | Add a page to it |
| `dashboard_id` + `page_id`, `spec.kind: "page"` | Update that page |
| Full path + `spec: null` | Delete the node the path points at |

You always pass the ID path down to the target's parent. Adding the target's own ID updates that node, and leaving it out creates a new one.

```json theme={null}
{
  "name": "set_dashboard",
  "arguments": {
    "dashboard_id": "<DASHBOARD_ID>",
    "page_id": "<PAGE_ID>",
    "spec": {
      "kind": "element",
      "config": { "type": "chart", "query_id": "<QUERY_ID>" }
    }
  }
}
```

Element `config.type` covers the visualization types above plus layout and control elements: `markdown`, `spacer`, `variable-select`, `switch`, `date-range`, and `radio-group`. Call `get_skill(name="dashboard-design")` for the build order and element catalog, then `get_skill(name="dashboard-design", reference_title="<config.type>")` for a type's full schema.

<Warning>
  Use these strings exactly as written for `config.type`: a dropdown is `variable-select`, not `select`. The skill's element catalog is the authoritative list.
</Warning>

<Tip>
  If the request touches a topic Terminal already covers, run `search_terminal` and `get_terminal_results` first and use that chart manifest and SQL as your baseline. See [Knowledge & discovery](/ai/mcp/tools-reference/knowledge#terminal-dashboards).
</Tip>

### Reading a dashboard

`read_dashboard` returns the node you target plus summaries of its immediate children, and it never returns a whole subtree.

| Arguments | Returns |
| :- | :- |
| `dashboard_id` | Name, settings, list of pages |
| `+ page_id` | The page plus its sections |
| `+ section_id` | The section plus its elements |
| `+ element_id` | The element's full typed config |

### Deleting

`delete_dashboard` takes a `dashboard_id` **only** and removes the whole dashboard. To remove a page, section, or element, call `set_dashboard` with `spec: null` and that node's ID path.

## Sharing

<Tabs>
  <Tab title="Share a query">
    ```json theme={null}
    {
      "name": "share_explorer_query",
      "arguments": {
        "query_id": "<QUERY_ID>",
        "visual_id": "<VISUAL_ID>",
        "exclude_sql": false
      }
    }
    ```

    `share_explorer_query` returns a share URL (`https://app.allium.so/s/{share_id}`) and an embed URL (`https://app.allium.so/embed/{share_id}`).

    Omit `visual_id` and the shared page shows the results table with one tab per saved visual, which is usually what you want when the query has several. Pass a `visual_id` and the page pins that one visual. Only this form renders a visual in the embed URL: without it, the embed shows the table.

    `exclude_sql` defaults to `false`, so the shared page shows your SQL unless you set it to `true`.
  </Tab>

  <Tab title="Share a dashboard">
    ```json theme={null}
    {
      "name": "share_dashboard",
      "arguments": { "dashboard_id": "<DASHBOARD_ID>" }
    }
    ```

    `share_dashboard` returns `https://app.allium.so/s/dashboard/{share_id}`. Calling it again on a dashboard that already has a public share returns the existing link. Dashboards have no embed URL.
  </Tab>
</Tabs>

<Warning>
  Anyone with a share link can view the content without logging in. There is no unshare tool: to stop sharing a dashboard, open it at `https://app.allium.so/analyze/dashboards/{dashboard_id}` and toggle off public access.
</Warning>

## Related resources

<CardGroup cols={2}>
  <Card title="SQL & queries" icon="database" href="/ai/mcp/tools-reference/sql-and-queries">
    Create the saved queries that back your charts
  </Card>

  <Card title="Skills" icon="book-open" href="/ai/mcp/tools-reference/skills">
    Fetch the exact spec schema for every visual and element type
  </Card>

  <Card title="Dashboards in the App" icon="chart-line" href="/app/visualisations">
    Build visuals and dashboards by hand in the App
  </Card>

  <Card title="Terminal dashboards" icon="magnifying-glass" href="/ai/mcp/tools-reference/knowledge#terminal-dashboards">
    Start from an analyst-built baseline
  </Card>
</CardGroup>