Widget types

API v3 is in preview

Endpoints and response shapes can change before general availability. 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 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:

area

6 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"

bar

9 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"

billboard

6 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"

heatmap

6 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"

histogram

6 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"

line

15 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"

pie

3 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"

scatter

5 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"