Dashboards API reference

The Dashboards API lets you programmatically manage Insights dashboards and their widgets. All dashboard endpoints are scoped to a project.

Get a dashboard list or dashboard details

curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/dashboards
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/dashboards/ID

The list endpoint returns results in a results array. The detail endpoint returns a single dashboard:

{
  "id": "abc123",
  "title": "My Dashboard",
  "widgets": [
    {
      "id": "4b2e9c1a-7f3d-4a12-9d5e-0b8f6a2c1e4d",
      "type": "insights_vis",
      "grid": { "x": 0, "y": 0, "w": 12, "h": 3 },
      "presentation": { "title": "Total requests" },
      "config": {
        "query": "filter event_type::str == \"request\" | stats count() by bin()",
        "vis": { "view": "line" },
        "streams": ["default"]
      }
    }
  ],
  "is_default": false,
  "shared": true,
  "default_ts": "P7D",
  "created_at": "2026-01-31T14:22:18Z",
  "updated_at": "2026-02-04T09:11:05Z",
  "project_id": 1
}

The response includes:

Field name	Type	Description
id	string	The dashboard’s hashid. Use this value in URLs for show, update, and delete requests.
title	string	The dashboard title.
widgets	array	The dashboard’s widgets, in source form (see below).
is_default	boolean	Whether this is the project’s default dashboard.
shared	boolean	Whether the dashboard is shared with other users on the account. Dashboards created via the API are shared.
default_ts	string	The dashboard’s default time range, if set. See default_ts under Create a dashboard for accepted values.
created_at	string	ISO 8601 timestamp.
updated_at	string	ISO 8601 timestamp.
project_id	integer	The project the dashboard belongs to.

In the response, each widget’s config.streams contains stream slugs (for example "default" or "internal") rather than numeric stream IDs. Use the same slugs when creating or updating widgets.

Create a dashboard

curl -u AUTH_TOKEN: \
  -X POST \
  -H 'Content-type: application/json' \
  -d '{"dashboard":{"title":"My Dashboard","widgets":[]}}' \
  https://app.honeybadger.io/v2/projects/ID/dashboards

Returns 201 Created with the dashboard JSON shown above.

The request body must be wrapped in a top-level dashboard object. These fields can be provided:

Field name	Type	Description
title	string	The dashboard title.
widgets	array	The dashboard’s widgets. See the widget fields below. Pass an empty array to create a dashboard with no widgets.
default_ts	string	Optional default time range. Accepts an ISO 8601 duration (P1D, P7D, PT1H), a keyword (today, yesterday, week, month), or a date range (2024-01-01/2024-01-31).

Widget fields

Each entry in the widgets array describes a single widget. The most common widget type is insights_vis, which renders a BadgerQL query as a chart or table:

Field name	Type	Description
type	string	The widget type, e.g. "insights_vis". Other built-in types include "alarms", "deployments", "checkins", "uptime", and "errors".
id	string	Optional UUID. If omitted, the server generates one. Must be unique within the dashboard. On update, include the existing widget’s id to preserve it; omitting it will regenerate the ID.
grid	object	Position and size on the dashboard grid. Keys: x, y, w, h. Defaults to {"x": 0, "y": 0, "w": 12, "h": 3} if omitted.
presentation	object	Display options. Keys: title, subtitle.
config	object	Widget-specific configuration. See below.

For insights_vis widgets, config accepts:

Field name	Type	Description
query	string	A BadgerQL query to execute.
vis.view	string	The visualization view. One of "table", "line", "bar", "area", "pie", "billboard", "histogram", "scatter", or "heatmap".
streams	array	Optional list of stream slugs to query (for example ["default"]). Defaults to all streams on the project.

Example with a widget

curl -u AUTH_TOKEN: \
  -X POST \
  -H 'Content-type: application/json' \
  -d '{
    "dashboard": {
      "title": "Traffic overview",
      "widgets": [
        {
          "type": "insights_vis",
          "grid": { "x": 0, "y": 0, "w": 12, "h": 3 },
          "presentation": { "title": "Total requests" },
          "config": {
            "query": "filter event_type::str == \"request\" | stats count() by bin()",
            "vis": { "view": "line" }
          }
        }
      ]
    }
  }' \
  https://app.honeybadger.io/v2/projects/ID/dashboards

The request body is validated against the dashboard schema. A 422 Unprocessable Entity response is returned when the payload violates the schema (unknown widget type, unknown properties, duplicate widget IDs, a title longer than 255 characters, etc.) or when the account’s dashboard or widget limit has been reached.

See the Insights dashboards guide for more on the widget catalog and schema. In the Honeybadger UI, the Edit Source view exposes the full YAML-equivalent of the same schema used by this API.

Update a dashboard

curl -u AUTH_TOKEN: \
  -X PUT \
  -H 'Content-type: application/json' \
  -d '{"dashboard":{"title":"Updated title","widgets":[]}}' \
  https://app.honeybadger.io/v2/projects/ID/dashboards/ID

Returns 204 No Content on success. The request body uses the same fields as Create a dashboard. The submitted widgets array replaces the existing one, so include every widget you want to keep.

Delete a dashboard

curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/dashboards/ID

Returns 204 No Content on success.