---
title: Widget types
description: 'Settings for each dashboard widget type in the Honeybadger API v3: the config keys each widget type accepts.'
url: https://docs.honeybadger.io/api/v3/dashboards/widget-types/
---

API v3 is in preview

Endpoints and response shapes [can change before general availability](https://docs.honeybadger.io/api/v3/#preview). API v2 is unchanged.

Each section covers one value of `type`: the fields it adds to the shared ones. The shared fields are listed first.

## Shared fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Kept as sent. Unique within its dashboard; another dashboard can use the same ID. Left out, the server assigns one. Use letters, digits, `-` and `_`. |
| `grid` | object | Merged into the default {x: 0, y: 0, w: 12, h: 3}: left out, the widget gets the default, and a key left out takes the default's value. Default: `{"x":0,"y":0,"w":12,"h":3}`. |
| `grid.x` | integer | Min 0. |
| `grid.y` | integer | Min 0. |
| `grid.w` | integer | Min 1. |
| `grid.h` | integer | Min 1. |
| `presentation` | object | |
| `presentation.title` | string | Max length 255. |
| `presentation.subtitle` | string | Max length 255. |

## alarms

2 settings

| Field | Type | Description |
| - | - | - |
| `config` | object | |
| `config.limit` | integer | Max alarms shown. Min 1. |
| `config.filter_state` | string | Show all alarms or only those in one state. Allowed values: `all`, `triggered`, `ok`. |
| `type` required | "alarms" | |

## checkins

2 settings

| Field | Type | Description |
| - | - | - |
| `config` | object | |
| `config.limit` | integer | Max check-ins shown. Min 1. |
| `config.sort_order` | string | Sort by state, name, or last report time. Allowed values: `state_name`, `name`, `last_reported`. |
| `type` required | "checkins" | |

## deployments

3 settings

| Field | Type | Description |
| - | - | - |
| `config` | object | |
| `config.limit` | integer | Max deploys shown. Min 1. |
| `config.override_time` | boolean | Use `ts` instead of the dashboard's time range. |
| `config.ts` | string | Time range used when `override_time` is true. |
| `type` required | "deployments" | |

## errors

3 settings

| Field | Type | Description |
| - | - | - |
| `config` | object | |
| `config.limit` | integer | Max errors shown. Min 1. |
| `config.query` | string | Error search query string to filter the list. |
| `config.sort` | string | Sort order. Allowed values: `last_seen_desc`, `last_seen_asc`, `times_desc`, `times_asc`. |
| `type` required | "errors" | |

## insights\_vis

5 settings

| Field | Type | Description |
| - | - | - |
| `config` | object | |
| `config.streams` | array\<string> | Streams to query, by slug: `default` (the project's own stream) or `internal`. Anything else is refused (422). Left out or empty, set to the project's current streams. A slug whose stream the project doesn't have yet, right after it's created, is dropped. Allowed values: `default`, `internal`. |
| `config.query` | string | BadgerQL query producing the widget's data. |
| `config.vis` | object | How to render the result: `{view, chart_config}`. See [Chart types](https://docs.honeybadger.io/api/v3/dashboards/widget-types/#chart-types) for each `view` value's fields. |
| `config.vis.view` required | string | Allowed values: `billboard`, `bar`, `line`, `pie`, `area`, `histogram`, `scatter`, `heatmap`, `table`. |
| `config.vis.chart_config` | object | |
| `type` required | "insights\_vis" | |

**Chart types.** The remaining `config.vis` fields depend on `config.vis.view`:

### area6 settings

| Field | Type | Description |
| - | - | - |
| `config.vis.chart_config` | object | Like line, with the area under each series filled; series can be stacked. |
| `config.vis.chart_config.xField` | string | Alias for the x axis, typically a time bin such as `bin(1h)`. |
| `config.vis.chart_config.yField` | string | Alias plotted as the series value; required when `groupType` is `events`. |
| `config.vis.chart_config.zField` | string | Alias whose distinct values split results into one series each. |
| `config.vis.chart_config.groupType` | string | `events` (default): one series from `yField`, split by `zField` if set; `fields`: every result field except `xField` becomes its own series. Allowed values: `fields`, `events`. |
| `config.vis.chart_config.stacked` | boolean | Stack series instead of overlaying them. |
| `config.vis.chart_config.groups` | object | Per-series display options keyed by series name, e.g. `{"web": {"color": "#4A90D9"}}`. Advanced — usually omit. |
| `config.vis.view` required | "area" | |

### bar9 settings

| Field | Type | Description |
| - | - | - |
| `config.vis.chart_config` | object | Bar chart of a value per category. |
| `config.vis.chart_config.categoryField` required | string | Alias for the category axis; one bar per distinct value. |
| `config.vis.chart_config.valueField` required | string | Alias for bar height. |
| `config.vis.chart_config.valueFieldUnit` | string | Unit used to format values: `percent`, `microseconds`, or `milliseconds`. |
| `config.vis.chart_config.labelField` | string | Alias rendered as a label on each bar. |
| `config.vis.chart_config.groupType` | string | `events` (default): series come from `groupField`; `fields`: every result field except `categoryField` becomes its own series. Allowed values: `fields`, `events`. |
| `config.vis.chart_config.groupField` | string | Alias whose distinct values split bars into series (with `groupType` `events`). |
| `config.vis.chart_config.horizontal` | boolean | Render bars horizontally. |
| `config.vis.chart_config.stacked` | boolean | Stack series instead of grouping side by side. |
| `config.vis.chart_config.groups` | object | Per-series display options keyed by series name, e.g. `{"web": {"color": "#4A90D9"}}`. Advanced — usually omit. |
| `config.vis.view` required | "bar" | |

### billboard6 settings

| Field | Type | Description |
| - | - | - |
| `config.vis.chart_config` | object | Big-number stat tiles: one tile per result row (or one per result field when `groupType` is `fields`). |
| `config.vis.chart_config.titleField` | string | Alias shown as the tile title. |
| `config.vis.chart_config.valueField` | string | Alias shown as the big number; required when `groupType` is `events`. |
| `config.vis.chart_config.titleURLField` | string | Alias containing a URL; makes the tile title a link. |
| `config.vis.chart_config.subtitleField` | string | Alias shown below the value. |
| `config.vis.chart_config.statusField` | string | Alias whose value drives the tile's status indicator. |
| `config.vis.chart_config.groupType` | string | `events` (default): one tile per result row using `valueField`; `fields`: one tile per result field. Allowed values: `fields`, `events`. |
| `config.vis.view` required | "billboard" | |

### heatmap6 settings

| Field | Type | Description |
| - | - | - |
| `config.vis.chart_config` | object | Grid of cells colored by intensity. The query must sort by the x and y fields (`\| sort x, y`) to render correctly. |
| `config.vis.chart_config.xField` required | string | Alias for the x axis, typically a time bin such as `bin(1h)`. |
| `config.vis.chart_config.yField` required | string | Alias for the y axis. |
| `config.vis.chart_config.zField` required | string | Alias for cell value/intensity. |
| `config.vis.chart_config.yFieldUnit` | string | Unit used to format y values: `percent`, `microseconds`, or `milliseconds`. |
| `config.vis.chart_config.steps` | integer | Number of color steps (default 5). Min 1. |
| `config.vis.chart_config.groups` | object | Per-series display options keyed by series name, e.g. `{"web": {"color": "#4A90D9"}}`. Advanced — usually omit. |
| `config.vis.view` required | "heatmap" | |

### histogram6 settings

| Field | Type | Description |
| - | - | - |
| `config.vis.chart_config` | object | Distribution of values across buckets. |
| `config.vis.chart_config.xField` required | string | Alias for the x axis. |
| `config.vis.chart_config.yField` required | string | Alias for the y axis. |
| `config.vis.chart_config.zField` | string | Alias whose distinct values split results into one series each. |
| `config.vis.chart_config.xFieldUnit` | string | Unit used to format x values: `percent`, `microseconds`, or `milliseconds`. |
| `config.vis.chart_config.yFieldUnit` | string | Unit used to format y values: `percent`, `microseconds`, or `milliseconds`. |
| `config.vis.chart_config.groups` | object | Per-series display options keyed by series name, e.g. `{"web": {"color": "#4A90D9"}}`. Advanced — usually omit. |
| `config.vis.view` required | "histogram" | |

### line15 settings

| Field | Type | Description |
| - | - | - |
| `config.vis.chart_config` | object | One or more series plotted over an x axis, usually time. |
| `config.vis.chart_config.xField` | string | Alias for the x axis, typically a time bin such as `bin(1h)`. |
| `config.vis.chart_config.yField` | string | Alias plotted as the series value; required when `groupType` is `events`. |
| `config.vis.chart_config.zField` | string | Alias whose distinct values split results into one series each. |
| `config.vis.chart_config.colorField` | string | Alias whose values supply explicit series colors. |
| `config.vis.chart_config.xFieldUnit` | string | Unit used to format x values: `percent`, `microseconds`, or `milliseconds`. |
| `config.vis.chart_config.yFieldUnit` | string | Unit used to format y values: `percent`, `microseconds`, or `milliseconds`. |
| `config.vis.chart_config.groupType` | string | `events` (default): one series from `yField`, split by `zField` if set; `fields`: every result field except `xField` becomes its own series. Allowed values: `fields`, `events`. |
| `config.vis.chart_config.yAxisLabel` | string | Left y-axis label (stored, but charts don't use it yet). |
| `config.vis.chart_config.yAxisMin` | number | Left y-axis minimum (stored, but charts don't use it yet). |
| `config.vis.chart_config.yAxisMax` | number | Left y-axis maximum (stored, but charts don't use it yet). |
| `config.vis.chart_config.rightYAxisFormat` | string | Right y-axis format (stored, but charts don't use it yet). |
| `config.vis.chart_config.rightYAxisLabel` | string | Right y-axis label (stored, but charts don't use it yet). |
| `config.vis.chart_config.rightYAxisMin` | number | Right y-axis minimum (stored, but charts don't use it yet). |
| `config.vis.chart_config.rightYAxisMax` | number | Right y-axis maximum (stored, but charts don't use it yet). |
| `config.vis.chart_config.groups` | object | Per-series display options keyed by series name, e.g. `{"web": {"color": "#4A90D9"}}`; entries may also set `axis` (`left`\|`right`) to plot a series on the right y axis. Advanced — usually omit. |
| `config.vis.view` required | "line" | |

### pie3 settings

| Field | Type | Description |
| - | - | - |
| `config.vis.chart_config` | object | Proportional slices; one slice per result row. |
| `config.vis.chart_config.nameField` required | string | Alias for slice labels. |
| `config.vis.chart_config.valueField` required | string | Alias for slice sizes. |
| `config.vis.chart_config.groups` | object | Per-slice display options keyed by slice name, e.g. `{"web": {"color": "#4A90D9"}}`. Advanced — usually omit. |
| `config.vis.view` required | "pie" | |

### scatter5 settings

| Field | Type | Description |
| - | - | - |
| `config.vis.chart_config` | object | Individual points plotted on two axes. |
| `config.vis.chart_config.xField` required | string | Alias for the x axis. |
| `config.vis.chart_config.yField` required | string | Alias for the y axis. |
| `config.vis.chart_config.groupField` | string | Alias whose distinct values color the points. |
| `config.vis.chart_config.scaleField` | string | Alias that scales point size. |
| `config.vis.chart_config.groups` | object | Per-series display options keyed by series name, e.g. `{"web": {"color": "#4A90D9"}}`. Advanced — usually omit. |
| `config.vis.view` required | "scatter" | |

### table

| Field | Type | Description |
| - | - | - |
| `config.vis.view` required | "table" | |
| `config.vis.chart_config` | object | Raw result rows and columns. No config. |

## uptime

1 setting

| Field | Type | Description |
| - | - | - |
| `config` | object | |
| `config.limit` | integer | Max uptime monitors shown. Min 1. |
| `type` required | "uptime" | |

---

## 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/)