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

# Dashboards

> Define dashboards and their widgets in YAML, versioned and reviewed like the rest of your config

A `kind: dashboard` declares a [dashboard](/documentation/observability/dashboards): its window, the filters over every widget, and its widgets top to bottom. A widget is an [analytics query](/documentation/observability/analytics-api) plus a name, a chart type and a size, so a query you tried over the API drops straight into a widget.

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json
kind: dashboard
name: frontdesk-health
displayName: Frontdesk health
timeRange: { type: LAST, value: 30, unit: DAYS }
filters:
  - { type: AGENT_PROPERTY, value: frontdesk }   # an agent by its config name, or its id
  - { type: MODALITY, value: call }
widgets:
  - name: Calls
    display: NUMBER
    size: SMALL
    measures:
      - type: CONVERSATION
  - name: Task completion
    display: LINE
    size: LARGE
    interval: DAY
    measures:
      - metric: task_completion
  - name: Call outcomes
    display: STACKED_BAR
    interval: WEEK
    measures:
      - metric: call_outcome      # a classification: counted and split by value
  - name: Calls by direction
    display: STACKED_BAR
    measures:
      - type: CONVERSATION
        breakdown: { type: CALL_PROPERTY, property: direction }
```

***

## Fields

| Field | Required | |
| :- | :- | :- |
| `name` | yes | The config name. |
| `displayName` | no | The title shown in Roark. Defaults to `name`. |
| `description` | no | Free text. |
| `isDefault` | no | Make it the project's default dashboard. Left out, the flag is left as it is. |
| `timeRange` | no | The window every widget reads. A new dashboard defaults to the last 30 days; left out on an existing one, whatever a viewer last picked is kept. Same shapes as an [analytics query](/documentation/observability/analytics-api#time-windows). |
| `filters` | no | Over every widget: `AGENT_PROPERTY`, `CALL_PROPERTY`, `MODALITY` or `DATASET`. Left out, a viewer's filters are kept. |
| `widgets` | no | Up to 50, top to bottom. |

### Widgets

| Field | Required | |
| :- | :- | :- |
| `name` | yes | The widget's title, unique on the dashboard. It is the widget's identity across applies. |
| `measures` | yes | 1 to 10 [measures](/documentation/observability/analytics-api#measures): `metric: <slug>`, or `type: CONVERSATION` / `type: UPTIME`, each with optional `aggregation`, `percentile`, `breakdown` and `filters`. |
| `display` | no | `LINE` (default), `NUMBER`, `RADAR`, `STACKED_BAR` or `TABLE`. |
| `size` | no | `SMALL`, `MEDIUM` (default), `LARGE` or `EXTRA_LARGE`. |
| `interval` | no | `HOUR`, `DAY` (default), `WEEK` or `MONTH`. Stepped coarser on wide windows. |
| `filters` | no | Applied to every measure in the widget. |
| `comparisonMode` | no | `PREVIOUS_PERIOD` to add the preceding window. |
| `comparisonGroups` | no | 2 to 5 named filter sets compared as separate series. |

***

## References

* **Metrics** resolve by slug: a [`kind: metric`](/documentation/config-as-code/metrics) in the same config (applied first), or any metric the project can see, system metrics included.
* **Agents** in an agent filter can be written by their config name; Roark resolves them to ids, the same way other kinds reference agents.

Every widget is checked against what its metric can answer before anything is written. A widget asking for `AVG` of a classification, or naming a metric that doesn't exist, fails that dashboard's apply with the reason, and the dashboard is left exactly as it was.

***

## In Roark

A dashboard created by config shows **Managed by config**. Its title and widgets are read-only in Roark and over the API (edits return `409`): change them in your config and re-apply. Anyone viewing it can still pick a time range and filter it, and an apply only overwrites those when the config declares `timeRange` or `filters`. Duplicating a managed dashboard gives you an editable copy.

A dashboard made in Roark with the same title as a `kind: dashboard` (its `displayName`, or `name`) is adopted on the first apply rather than duplicated, as long as exactly one unmanaged dashboard has that title.

***

## Removing a dashboard

Deleting a dashboard from your config (with prune on, the default) deletes the dashboard and its widgets.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.