--- title: Dashboards API reference description: API reference for managing Insights dashboards with endpoints to create, read, update, and delete dashboards and their widgets. url: https://docs.honeybadger.io/api/dashboards/ --- The Dashboards API lets you programmatically manage [Insights dashboards](https://docs.honeybadger.io/guides/dashboards/) and their widgets. All dashboard endpoints are scoped to a project. ## Get a dashboard list or dashboard details ```bash 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: ```json { "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](https://docs.honeybadger.io/api/dashboards/#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 ```bash 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](https://docs.honeybadger.io/guides/insights/badgerql/) 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 ```bash 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](https://docs.honeybadger.io/guides/dashboards/) 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 ```bash 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](https://docs.honeybadger.io/api/dashboards/#create-a-dashboard). The submitted `widgets` array replaces the existing one, so include every widget you want to keep. ## Delete a dashboard ```bash curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/dashboards/ID ``` Returns `204 No Content` on success. --- ## 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/)