# Dashboards

> Your own dashboards of live numbers from every product, for one business or across all of them, built from a list of metrics, never SQL.

A dashboard is a grid of **widgets** fed by live data from everything thelastapi runs for you: payments, analytics, session replay, sign-in, AI and spend, email, hosting, phone, social and connectors. Build a churn dashboard, a traffic dashboard, an AI-cost dashboard, or a portfolio of every business side by side. Each widget is a **type** (a number, a chart, a table…) plus a **metric** picked from a catalogue, plus its options. Nobody writes a query.

Dashboards live at two levels:

| Level | Where | Reads |
| --- | --- | --- |
| **Project** | console ▸ a project ▸ **Dashboards**, `project_id` set | that business |
| **Account** | console ▸ **Dashboards**, no `project_id` | every business, or the ones in `project_ids`; any widget can break down by business |

People make them in the console; agents make them with `vibiz dashboards`, the `vibiz_dashboards` tool, the SDK or `POST /v1/dashboards`. Every answer has a `console_url` that opens the dashboard with its range.

## Templates

One call makes a whole dashboard you can then change:

| Template | Level | What is on it |
| --- | --- | --- |
| `churn` | project | revenue, MRR, active subscribers, churn rate, MRR and revenue over time, new and churned subscriptions, a retention grid by month, revenue per customer, refunds, latest payments |
| `traffic` | project | visitors, pageviews, custom events, sessions with errors, visitors by day, sources, top pages, countries, devices, sessions with problems to watch |
| `ai_cost` | project | AI spend and calls, spend on every product, AI spend by day and model, spend by model and by product |
| `growth` | project | sign-ups, active users, users, visitors, sign-ups by day, latest sign-ups |
| `portfolio` | account | revenue, MRR, visitors and AI spend across businesses, a row per business, revenue and visitors by business, AI spend and errors by business |

```bash
vibiz dashboards create --template churn          # in the app's folder: this project
vibiz dashboards create --template portfolio      # the account, every business
```

## Widget types

The grid has 12 columns; each widget has a `layout` `{ x, y, w, h }` (rows of 64 px). Leave `layout` out and it goes in the first free spot. On a phone, widgets stack top to bottom.

| Type | Shows | Metric shape |
| --- | --- | --- |
| `stat` | one number for the range, with its change against the period before (red when a rise is bad: churn, errors, spend) | scalar |
| `line` | a number over time; with a breakdown, one line per value | timeseries |
| `area` | the same, filled; with a breakdown, stacked | timeseries |
| `bar` | columns over time (stacked by the breakdown), or bars for a breakdown like countries | timeseries or table |
| `table` | a breakdown as rows (value and share) | table |
| `list` | the latest items: payments, sign-ups, deploys, sessions with problems, each with its console link | table |
| `funnel` | visitors who reached each step in order, and the drop between steps | funnel |
| `cohort` | retention by month of start | cohort |
| `text` | a heading or a note in markdown (`#`, `-`, `**bold**`) | none |

## Options

| Option | Meaning |
| --- | --- |
| `range` | `24h`, `7d`, `30d`, `90d`, `12m`: this widget's own range (a request's range wins) |
| `bucket` | `hour`, `day`, `week`, `month` for charts; by default it fits the range |
| `breakdown` | one of the metric's breakdowns (`project` at the account level, `source`, `country`, `model`…) |
| `filters` | equality filters the metric lists: `{ "country": "US" }`, `{ "source": "Google" }`, `{ "environment": "development" }` |
| `limit` | rows of a table or list, or series of a chart (the rest are summed as Other); 1 to 50 |
| `steps` | a funnel's steps in order: a page (`/pricing`) or an event name (`Signup`) |

## The metric catalogue

`GET /v1/dashboards/metrics` (or `vibiz dashboards metrics`) lists every metric with its levels, shapes, breakdowns, filters, unit and the permission a Limited key needs. Money is in US cents (`usd_cents`); AI and product spend in millionths of a dollar (`usd_micro`). Every metric works at both levels unless it says otherwise, and every one that can be split takes `project` as a breakdown at the account level.

| Metric | What it is | Breakdowns | Unit |
| --- | --- | --- | --- |
| `payments.revenue` | sales net of refunds (other currencies as they settled), by the day of the sale | currency | usd_cents |
| `payments.sales` | payments that went through | currency | count |
| `payments.refunds` | refunded of the sales in the range | | usd_cents |
| `payments.mrr` | monthly recurring revenue of paying subscriptions; over time, at the end of each period | | usd_cents |
| `payments.active_subscribers` | active, trialing and past due subscriptions | | count |
| `payments.new_subscriptions` | subscriptions started | | count |
| `payments.churned_subscriptions` | subscriptions canceled | | count |
| `payments.churn_rate` | canceled in the period over active at its start | | percent |
| `payments.arpu` | revenue over the customers who paid | | usd_cents |
| `payments.latest` | the newest payments (customers' emails masked for a Limited key without live payment details) | | list |
| `payments.subscription_retention` | cohorts by month of start, share still paying each month after (at least the last 6 months) | | percent |
| `analytics.visitors` | unique visitors (a visitor counts once a day) | source, country, device, page | count |
| `analytics.pageviews` | pages viewed | source, country, device, page | count |
| `analytics.events` | custom and server-side events | event, page, country | count |
| `analytics.funnel` | visitors through `steps`, same visitor, same day | | funnel |
| `replay.sessions` | recorded sessions | device, country | count |
| `replay.error_sessions` | sessions with a JavaScript error | device, country | count |
| `replay.errors` | JavaScript errors | device, country | count |
| `replay.rage_clicks` | rage clicks | device, country | count |
| `replay.dead_clicks` | dead clicks | device, country | count |
| `replay.problem_sessions` | the latest sessions with problems, each with a link to watch it | | list |
| `sign_in.signups` | accounts created in the app | | count |
| `sign_in.active_users` | users who signed in | | count |
| `sign_in.users` | every account, now | | count |
| `sign_in.latest_signups` | the newest accounts | | list |
| `ai.spend` | what AI calls cost | model, kind | usd_micro |
| `ai.calls` | AI calls | model, kind | count |
| `usage.spend` | what every product cost | product, tool | usd_micro |
| `email.sent` | emails the app sent | | count |
| `email.received` | messages in the business's inbox | | count |
| `email.newsletter_sends` | broadcast and automation emails sent | kind, status | count |
| `email.opens` | newsletter emails opened by a person | kind | count |
| `email.bounces` | newsletter emails that bounced | kind | count |
| `email.new_contacts` | contacts added to the list | status | count |
| `hosting.deploys` | deployments started | status, target | count |
| `hosting.latest_deploys` | the newest deployments | | list |
| `phone.calls` | calls made and received | direction, status | count |
| `phone.messages` | texts sent and received | direction | count |
| `social.posts_published` | social posts that went out | | count |
| `connectors.calls` | calls to your own APIs through connectors | status, risk | count |
| `portfolio.projects` | account only: one row per business with visitors, revenue, sales, MRR, AI spend, sessions with errors and deploys | | table |

Payments metrics read production unless `filters.environment` is `development`.

## Who can see what

Any key can make and change dashboards: they are views. What a widget **reads** keeps the permission of reading it directly ([Keys](https://thelastapi.dev/docs/keys)):

- **Sign-in** metrics read the app's own production database: a Limited key needs `database.production:read`. Without it, that widget alone answers `forbidden` with the permission and a `grant_url` (the page where the owner allows it); the rest of the dashboard still loads. Set the widget's `filters.environment` to `development` to read the development database instead.
- **Latest payments** shows customers' emails masked unless the key has `payments.live:read`, as the payments list does. Totals (revenue, MRR, churn) are readable by any key, as `GET /v1/projects/:id/payments/revenue` is.
- Every dashboard and every business is the account's own: another account's dashboard or project is `404`.

## Errors that say what to fix

A spec with problems is refused with every problem named by its field, why, and what would work:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "widgets.0.metric: \"payments.mrrr\" isn't a metric (did you mean payments.mrr?); widgets.1.type: a funnel widget can't show payments.revenue (it answers scalar, timeseries, table).",
    "details": {
      "field": "widgets.0.metric",
      "problems": [
        { "field": "widgets.0.metric", "message": "widgets.0.metric: \"payments.mrrr\" isn't a metric (did you mean payments.mrr?)" },
        { "field": "widgets.1.type", "message": "widgets.1.type: a funnel widget can't show payments.revenue (it answers scalar, timeseries, table)" }
      ],
      "next_step": "Pick one from GET /v1/dashboards/metrics (vibiz dashboards metrics)."
    }
  }
}
```

When reading data, each widget fails on its own: `widgets[].error` has `code`, `message` and `details.next_step`, and the console shows it in the widget with the link to fix it.

## In the console

- **Dashboards** in the sidebar is the account's; a project's sidebar has its own **Dashboards**.
- **New dashboard**: a template or blank. **Edit** shows each widget's controls: move (arrows), narrower and wider, shorter and taller, rename and remove; whatever a widget is moved onto slides down. **Add widget** browses the metrics by product, shows the types each fits and a live preview before adding it.
- The range (`?range=30d`, or `?from=2026-10-01&to=2026-10-31`), the business picked on an account dashboard (`?projects=<id>`) and edit mode (`?edit=1`) are in the URL, so a link opens the same view.
- Numbers are kept a minute; the refresh button reads them again now.

## From an agent

```bash
vibiz dashboards                                   # this project's dashboards (--level account: the account's)
vibiz dashboards metrics --product payments        # the catalogue
vibiz dashboards create --template traffic --open
vibiz dashboards create "Weekly numbers" --level account
vibiz dashboards add-widget dsh_… --type table --metric analytics.visitors --breakdown country --limit 8
vibiz dashboards add-widget dsh_… --type funnel --metric analytics.funnel --steps /,/pricing,Signup
vibiz dashboards show dsh_… --range 7d              # every widget's numbers, and the link
vibiz dashboards rm-widget dsh_… w_… | rm dsh_… | open dsh_…
```

MCP: `vibiz_dashboards { action: "metrics" | "list" | "create" | "get" | "data" | "update" | "delete" | "add_widget" | "update_widget" | "remove_widget" | "query", … }`. `query` reads one unsaved widget, to try a metric before adding it.

SDK:

```ts
const d = await vibiz.dashboards.create({ template: 'churn', project_id: 'prj_…' });
await vibiz.dashboards.addWidget(d.id, {
  type: 'line',
  metric: 'analytics.visitors',
  options: { breakdown: 'source', limit: 5 },
});
const data = await vibiz.dashboards.data(d.id, { range: '90d' });
for (const w of data.widgets) console.log(w.title, w.error?.message ?? w.data);
```

## API

| Route | Does |
| --- | --- |
| `GET /v1/dashboards/metrics` | the catalogue: metrics, widget types, ranges, buckets, templates |
| `GET /v1/dashboards` | the dashboards; `?project_id=` one project's, `?level=account` the account's |
| `POST /v1/dashboards` | `{ name, project_id?, project_ids?, range?, widgets?, template? }` → `201` |
| `GET /v1/dashboards/:id` | one dashboard and its widgets |
| `PATCH /v1/dashboards/:id` | `{ name?, description?, range?, project_ids?, widgets? }`; `widgets` replaces the list |
| `DELETE /v1/dashboards/:id` | delete it (the data stays) |
| `POST /v1/dashboards/:id/widgets` | add one widget |
| `PATCH /v1/dashboards/:id/widgets/:widgetId` | change one widget |
| `DELETE /v1/dashboards/:id/widgets/:widgetId` | remove one widget |
| `GET /v1/dashboards/:id/data` | every widget's data: `?range=` or `?from=&to=`, `?project_ids=a,b`, `?widget=`, `?refresh=1` |
| `POST /v1/dashboards/query` | one unsaved widget's data |

A widget's data, by shape:

```json
{ "shape": "scalar", "unit": "usd_cents", "value": 482300, "previous": 401200, "change_pct": 20 }
{ "shape": "timeseries", "unit": "count", "bucket": "day", "keys": ["2026-11-11", "…"],
  "series": [{ "key": "Google", "label": "Google", "values": [12, 15], "total": 27 }] }
{ "shape": "table", "unit": "count", "columns": [{ "key": "label", "label": "Source" }, { "key": "value", "label": "Visitors" }],
  "rows": [{ "key": "Google", "label": "Google", "value": 27, "share": 61.4 }] }
{ "shape": "funnel", "unit": "count", "steps": [{ "step": "/pricing", "visitors": 120, "rate_from_start": 100, "rate_from_previous": null }] }
{ "shape": "cohort", "unit": "percent", "periods": 6, "cohorts": [{ "key": "2026-06", "label": "Jun 2026", "size": 40, "values": [100, 92.5, 85] }] }
```
