List dashboards

GET https://app.honeybadger.io/v3/projects/{project_id}/dashboards

Required scope dashboards:read

Returns a list of Insights dashboards for the project.

Example request

curl "https://app.honeybadger.io/v3/projects/$PROJECT_ID/dashboards" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN"

Parameters

Path parameters

Field	Type	Description
`project_id` required	string	Project ID.

Query parameters

Field	Type	Description
`page`	integer	Page number (1-indexed). Default: `1`. Min 1.
`per_page`	integer	Items per page. Default: `25`. Min 1, max 100.

Responses

200 Success

Example payload

{
  "data": [
    {
      "id": "Db4rKn",
      "project_id": "Xk9mZp",
      "title": "Performance Overview",
      "widgets": [
        {
          "id": "checkout-errors",
          "type": "insights_vis",
          "grid": {
            "x": null,
            "y": null,
            "w": null,
            "h": null
          },
          "presentation": {
            "title": "Checkout errors",
            "subtitle": "Last 24 hours"
          },
          "config": {}
        }
      ],
      "is_default": true,
      "shared": true,
      "default_ts": "PT3H",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "links": {
        "web": "https://app.honeybadger.io/projects/Xk9mZp"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25
  },
  "links": {
    "self": "/v3/projects/Xk9mZp/dashboards?page=2&per_page=25",
    "first": "/v3/projects/Xk9mZp/dashboards?page=1&per_page=25",
    "prev": "/v3/projects/Xk9mZp/dashboards?page=1&per_page=25",
    "next": "/v3/projects/Xk9mZp/dashboards?page=3&per_page=25"
  },
  "meta": {
    "request_id": "6f1c2b0e-8d4a-4f6e-9b2a-3c5d7e9f1a2b"
  }
}

Response schema33

Field	Type	Description
`data` required	array<object>
`data[].id` required	string
`data[].project_id` required	string	ID of the project this dashboard belongs to.
`data[].title` required	string	Dashboard title.
`data[].widgets` required	array<object>	The dashboard's widgets, in the order they were written and in the same shape a write accepts, including `config.streams` as stream slugs.
`data[].widgets[].id`	string	Kept as sent, or generated when left out. Send it back on update to keep the widget.
`data[].widgets[].type` required	string	Which kind of widget, and therefore which config shape applies. Allowed values: `insights_vis`, `alarms`, `deployments`, `checkins`, `uptime`, `errors`.
`data[].widgets[].grid`	object	Position and size on the dashboard grid.
`data[].widgets[].grid.x`	integer	Min 0.
`data[].widgets[].grid.y`	integer	Min 0.
`data[].widgets[].grid.w`	integer	Min 1.
`data[].widgets[].grid.h`	integer	Min 1.
`data[].widgets[].presentation`	object	Display-only chrome.
`data[].widgets[].presentation.title`	string	Max length 255.
`data[].widgets[].presentation.subtitle`	string	Max length 255.
`data[].widgets[].config`	object	Type-specific configuration. Its fields depend on `type`; the DashboardWidgetConfig schema for each type lists them.
`data[].is_default` required	boolean	Whether this is the default dashboard.
`data[].shared` required	boolean	Whether the dashboard is shared with all team members.
`data[].default_ts` required	string \| null	Default time range for the dashboard.
`data[].created_at` required	date-time	When the dashboard was created.
`data[].updated_at` required	date-time	When the dashboard was last updated.
`data[].links` required	object	Links into the Honeybadger web UI.
`data[].links.web` required	uri	The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have `links`. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on.
`pagination`	object	Offset-based pagination information.
`pagination.page` required	integer	Current page number. Min 1.
`pagination.per_page` required	integer	Items per page. Min 1, max 100.
`links`	object	Navigation links for a numbered-page collection. Each link is a root-relative path (`/v3/...`); resolve it against the API host.
`links.self` required	uri-reference	This page.
`links.first`	uri-reference	First page.
`links.prev`	string \| null	Previous page, or null on the first page.
`links.next`	string \| null	Next page, or null on the last page.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

Errors

401 Unauthorized

The credential is missing, invalid, expired or revoked (unauthorized), or was sent in a way v3 doesn’t accept (see the examples).

Example payload: unauthorized (Missing, malformed, expired or revoked credential)

{
  "error": {
    "code": "unauthorized",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: unsupported_auth_scheme (Sent as HTTP basic, which v3 does not accept)

{
  "error": {
    "code": "unsupported_auth_scheme",
    "message": "Send the credential as `Authorization: Bearer <token>`; v3 does not accept HTTP basic"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: credential_in_query (Sent as the `auth_token` query parameter)

{
  "error": {
    "code": "credential_in_query",
    "message": "Credentials must be sent in the Authorization header"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

403 Forbidden

The credential isn’t allowed to do this. error.code says why. An account or project the credential doesn’t cover is 404 not_found, not 403.

Example payload: access_denied (The credential isn't allowed to do this to this record)

{
  "error": {
    "code": "access_denied",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: insufficient_scope (The credential lacks the permission this endpoint requires)

{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {
      "required_scope": "faults:write",
      "token_scopes": [
        "faults:read",
        "insights:read"
      ]
    }
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: requires_user_token (The endpoint records who acted, and an account token has nobody)

{
  "error": {
    "code": "requires_user_token",
    "message": "This endpoint records the person who acted, so it requires a user credential rather than an account token"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: project_restricted (A project-restricted credential cannot create a project)

{
  "error": {
    "code": "project_restricted",
    "message": "Project-restricted tokens cannot create projects"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

404 Not Found

Resource not found

Example payload

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

422 Unprocessable Content

No path names the account, so the API token has to. This is returned when the token covers more than one account and the account a request applies to cannot be determined. Use a token bound to a single account.

Example payload

{
  "error": {
    "code": "ambiguous_account",
    "message": "This credential covers more than one account, so the account a request applies to is ambiguous. Use a token bound to a single account."
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.