---
title: Dashboards for AI agents
description: 'Insights dashboard structure: the dashboard object, widget types and their configs, grid layout, and the vis object.'
url: https://docs.honeybadger.io/resources/llms/instructions/dashboards/
---

This page is written for AI agents

It is generated from the Honeybadger codebase and published as part of our [instructions for AI agents](https://docs.honeybadger.io/resources/llms/instructions/). Agents and tools should fetch the raw version at [`/resources/llms/instructions/dashboards.txt`](https://docs.honeybadger.io/resources/llms/instructions/dashboards.txt); the machine-readable catalog is at [`/resources/llms/instructions/index.json`](https://docs.honeybadger.io/resources/llms/instructions/index.json). For the human documentation on this topic, see [the guides](https://docs.honeybadger.io/guides/dashboards/).

A dashboard is a collection of widgets displayed on a project’s Insights page.

Companion reading: widget queries are BadgerQL (see the BadgerQL reference), the **queries** instructions cover query fundamentals and `${...}` parameters, and the **charts** instructions cover `chart_config` fields.

## Dashboard object

* `title`: string, required (max 255 characters)
* `default_ts`: string, optional — default time range as an ISO 8601 duration (`PT3H`, `P1D`) or keyword (`today`, `yesterday`, `week`, `month`)
* `widgets`: array of widget objects, required

## Widget object

* `type`: string, required — one of the widget types below
* `id`: string — omit when creating a widget; the server assigns one. A widget without an `id` is treated as new. Preserve existing `id`s when updating a dashboard so widget state and history are retained
* `grid`: object — layout position `{x, y, w, h}` (see Grid layout)
* `presentation`: object — `{title, subtitle}` display strings (max 255 characters each)
* `config`: object — type-specific configuration

## Widget types and purposes

* `insights_vis` — renders a BadgerQL query as a chart or table; the primary building block
* `errors` — list of the project’s errors, optionally filtered by a search query (syntax: see the **errors** instructions)
* `alarms` — current status of the project’s Insights alarms
* `deployments` — recent deploy history
* `checkins` — check-in statuses
* `uptime` — uptime monitor statuses

## Config fields by widget type

Valid widget `type` values: `insights_vis`, `alarms`, `errors`, `deployments`, `checkins`, `uptime`.

### `insights_vis`

* `streams`: array of default|internal — Streams to query (defaults to \[“default”])
* `query`: any — BadgerQL query producing the widget’s data
* `vis`: any — How to render the result: `{view, chart_config}`

### `alarms`

* `limit`: integer, minimum 1 — Max alarms shown
* `filter_state`: string (all|triggered|ok) — Show all alarms or only those in one state

### `errors`

* `limit`: integer, minimum 1 — Max errors shown
* `query`: string — Error search query string to filter the list
* `sort`: string (last\_seen\_desc|last\_seen\_asc|times\_desc|times\_asc) — Sort order

### `deployments`

* `limit`: integer, minimum 1 — Max deploys shown
* `override_time`: boolean — Use `ts` instead of the dashboard’s time range
* `ts`: string — Time range used when `override_time` is true

### `checkins`

* `limit`: integer, minimum 1 — Max check-ins shown
* `sort_order`: string (state\_name|name|last\_reported) — Sort by state, name, or last report time

### `uptime`

* `limit`: integer, minimum 1 — Max uptime monitors shown

## The vis object (`insights_vis` widgets)

`config.vis` controls how the query result renders:

* `view`: string, required — one of `table`, `billboard`, `line`, `area`, `bar`, `histogram`, `scatter`, `heatmap`, `pie`
* `chart_config`: object, optional — view-specific options. For the fields each view accepts, see the **charts** instructions; do not invent fields

Example widget:

```json
{
  "type": "insights_vis",
  "presentation": {"title": "Errors Over Time"},
  "grid": {"x": 0, "y": 0, "w": 6, "h": 4},
  "config": {
    "query": "filter event_type::str == \"notice\" | stats count() as count by bin(1h)",
    "vis": {"view": "line"}
  }
}
```

## Grid layout

Dashboards use a 12-column grid:

* `x` — column offset (0–11)
* `y` — row offset (0 = top)
* `w` — width in columns (1–12)
* `h` — height in row units

Widgets must not overlap. A widget’s `y` must be >= the `y + h` of any widget above it in the same columns. Side-by-side widgets in the same row share the same `y`; the next row starts at `y + h` of the tallest widget in the current row. Plan the full layout before assigning positions — overlapping or misaligned widgets render incorrectly.

Example two-column layout:

```plaintext
Row 0:  Widget A: {x:0, y:0, w:6, h:4}    Widget B: {x:6, y:0, w:6, h:4}
Row 4:  Widget C: {x:0, y:4, w:12, h:4}
Row 8:  Widget D: {x:0, y:8, w:6, h:3}    Widget E: {x:6, y:8, w:6, h:3}
```

## Validation

Dashboard structure IS validated on save: unknown keys anywhere in the dashboard, widget, config, or chart\_config objects are rejected.

Widget queries are NOT validated when a dashboard is saved — a widget with a broken query silently renders empty or shows an error. Verify each query returns the expected data before saving it into a dashboard.

Widget queries may use query parameters — `${name}` or `${name:-default}` (syntax: see the **queries** instructions). Parameter values come from the dashboard URL’s query parameters and apply dashboard-wide, so every widget referencing `${env}` resolves to the same value. Give each parameter the same inline default everywhere it appears; a parameter that lacks both a URL value and a default blocks that widget from running.

---

## Try Honeybadger for FREE

Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice.

[Start free trial](https://app.honeybadger.io/users/sign_up)

[See plans and pricing](https://www.honeybadger.io/plans/)