# Custom dashboards across your sites

> Build custom dashboards from metric, chart, breakdown, goal, funnel, live visitor, uptime and Web Vitals cards, mixing any sites you can access in a workspace.

A custom dashboard is a named page of cards. Each card is a small report
for one site, and one dashboard can mix cards from any sites you can
access in the workspace, for example one dashboard per team or client.

Open **Dashboards** in the Workspace section of the sidebar. The list is
sorted by name and shows how many cards each dashboard has. Dashboards
belong to the workspace, so every member who can read analytics sees the
same list.

## Creating and editing

Click **New dashboard** (or press `N` on the list). On a dashboard, click
**Edit** (or press `E`) to change it, or **Delete** to remove it after a
confirmation.

1. Give the dashboard a **name** (required, up to 100 characters).
2. Click **Add card** and choose the card's type and site. The title is
   optional (up to 80 characters). Without one, the card is headed with
   its type.
3. Set the options for that type. The form shows only the options the
   chosen type uses.
4. Use the arrow buttons to move a card up or down, and the remove button
   to drop it. Cards appear on the dashboard in the order of the list.
5. Click **Save dashboard**.

A dashboard holds up to 40 cards. At 40, **Add card** is turned off.

> **Tip:** `N` and `E` are part of the
> [keyboard shortcuts](/docs/dashboard/keyboard-shortcuts), which you can
> turn off in your [account settings](/docs/dashboard/account-settings).

## Card types

| Type | What it shows | Options |
|---|---|---|
| **Metric** | One metric for the period, the change against the previous period and the previous value | Period, metric |
| **Chart** | One metric over time. On wide screens it takes two columns | Period, metric |
| **Breakdown** | The top 5 values of one dimension, with visitors (pageviews for pages, completions for events) | Period, breakdown |
| **Goals** | Up to 5 of the site's [goals](/docs/features/goals), most completions first, with their conversions | Period |
| **Live visitors** | Visitors in the last 5 minutes | None |
| **Funnel** | A [funnel](/docs/features/funnels)'s overall conversion rate, and the count and conversion rate at each step | Period, funnel id (optional) |
| **Uptime** | Up to 5 of the site's [uptime checks](/docs/features/uptime), with their status and uptime over the last 7 days | None |
| **Web Vitals** | The 75th percentile and rating of LCP, INP, CLS, FCP and TTFB. See [Performance](/docs/features/performance) | Period |

The **breakdown** option offers Page, Channel, Referrer, UTM source, UTM
campaign, Country, Device, Browser, Operating system, Entry page and
Event. It starts on Page.

The **funnel id** is the funnel's id, which starts with `fun_`. Leave it
empty and the card shows the site's oldest funnel.

## Periods and metrics

Each card has its own period, counted in its site's timezone. Choose any
[date range preset](/docs/dashboard/date-ranges#presets), from Today to
All time. The default is Last 30 days. Custom date ranges, filters and
segments are not part of a card.

Metric and Chart cards show one metric: Visitors (the default), Visits,
Pageviews, Views / visit, Bounce rate, Visit duration or Revenue (in the
site's currency).

The numbers come from the same reports as the site's own pages, so a card
and the site's [Overview](/docs/dashboard/overview) agree for the same
period. See [Metrics](/docs/metrics) for how each one is counted.

## Permissions

| Action | Permission | Built-in roles |
|---|---|---|
| View the list, a dashboard and its cards | `analytics.read` | Owner, Admin, Editor, Analyst, Viewer |
| Create, edit and delete dashboards | `content.write` | Owner, Admin, Editor, Analyst |

See [Roles and permissions](/docs/teams/roles) for the full matrix.

Site access applies card by card:

- The site list in the form holds only the sites you can access. Saving a
  new card for any other site is refused.
- A card for a site you can't access shows "You don't have access to this
  card's site." in place of its data. The rest of the dashboard works as
  usual.
- When you edit a dashboard, cards that a member with wider access added
  are kept, even for sites you can't see.

## How cards load

The dashboard opens at once and each card then loads by itself as it
comes into view, so a slow card never holds up the others. Until its data
arrives, a card shows its title and "Loading…".

- The site name in a card's header opens that site's overview for the
  card's period.
- A card with nothing to report says "Nothing to show for this card yet.",
  for example a Funnel card on a site without funnels or an Uptime card
  on a site without checks.
- Cards load once per page view. Reload the page for fresh numbers.

Cards sit in one column on phones, two on tablets and three on wide
screens.

## API

Dashboards are a REST resource under
`/workspaces/<workspace id>/dashboards` and MCP tools named `dashboards_*`
(`dashboards_list`, `dashboards_get`, `dashboards_create`,
`dashboards_update`, `dashboards_delete`). Dashboard ids start with
`dash_`. The [API reference](/docs/api) lists every input.

A card is an object with a `type`, a `site_id`, an optional `title` and
`params`:

```json
{
  "name": "Client: Acme",
  "cards": [
    { "type": "metric", "site_id": "pa_7Q2K9XH3AB",
      "params": { "period": "7d", "metric": "pageviews" } },
    { "type": "breakdown", "site_id": "pa_7Q2K9XH3AB", "title": "Countries",
      "params": { "dimension": "country", "limit": 10 } }
  ]
}
```

| `type` | `params` |
|---|---|
| `metric` | `period`, `metric` |
| `chart` | `period`, `metric`, `interval` |
| `breakdown` | `period`, `dimension`, `limit` |
| `goal` | `period`, `limit` |
| `funnel` | `period`, `funnel_id` |
| `live` | None |
| `uptime` | `limit` |
| `vitals` | `period` |

- `limit` is the number of rows, from 1 to 10 (default 5).
- `dimension` takes any [dimension](/docs/api/filters#dimensions),
  including `prop:<key>`.
- `interval` takes the chart [intervals](/docs/dashboard/date-ranges#intervals)
  (default `auto`).
- Params a type does not use are dropped. A card with an unknown type,
  period, metric or dimension is refused, and the error names the card's
  position.
- Sending `cards` in an update replaces the whole list.

> **Note:** The form has no fields for `limit` and `interval`, so saving
> a dashboard from the form resets them to their defaults.

`GET /workspaces/<workspace id>/dashboards/<dashboard id>/cards/<index>`
(MCP: `dashboards_card`) returns the data for one card, counting from 0.
Its `status` is `ok`, `no_access` or `not_available`.