--- title: "Get a dashboard" method: GET path: "/api/v3/dashboards/{dashboardId}" tags: ["V3 Dashboards"] --- # Get a dashboard `GET /api/v3/dashboards/{dashboardId}` ## Request - Base URL: `https://app.formbricks.com` - URL: `https://app.formbricks.com/api/v3/dashboards/{dashboardId}` - Auth: one of: - API key in cookie `next-auth.session-token` - API key in header `x-api-key` - HTTP bearer Returns a dashboard with every widget and its full chart, so one call tells a caller what is on it. Read each widget's numbers from `GET /api/v3/charts/{chartId}/data`. The workspace is resolved from the dashboard, so the operation takes no query parameters. Needs read access to the dashboard's workspace; a dashboard the caller cannot see, or that does not exist, answers 403. ## Path parameters - `dashboardId` string, cuid2, required ## Response `200` The dashboard - object - `data` DashboardResource, required: A dashboard: a named grid of widgets in a workspace. Its charts can come from different Feedback Datasets. Each widget's data is read separately, from `GET /api/v3/charts/{chartId}/data`. - `id` string, cuid2, required - `workspaceId` string, cuid2, required - `name` string, required: Unique within the workspace. - `creator` DashboardCreator, nullable, required: Who created the dashboard, for display only; `null` once that user is gone. - `name` string, required - `widgets` DashboardWidget[], required: In display order. - `id` string, cuid2, required - `chartId` string, cuid2, required - `layout` WidgetLayout, required: A widget's position and size on the dashboard's 12-column grid, in whole grid units: `1 ≤ w ≤ 12`, `x + w ≤ 12`, `1 ≤ h ≤ 8`, `0 ≤ y ≤ 1000`. Widgets may not overlap; gaps are allowed and close upward when the dashboard is drawn. - `x` integer, required - `y` integer, required - `w` integer, required - `h` integer, required - `order` integer, required - `chart` ChartResource, required: A chart: one saved visualisation of one Feedback Dataset. It belongs to a workspace and can sit on any number of dashboards — `dashboards` lists them, so a caller can see what an edit or a delete would affect. - `id` string, cuid2, required - `workspaceId` string, cuid2, required - `datasetId` string, cuid2, required: The Feedback Dataset the chart reads. Fixed when the chart is created. - `name` string, required: Unique within the workspace. - `type` 'area' | 'bar' | 'pie' | 'big_number' | 'matrix', required - `query` ChartQuery, required: What a chart computes, in Cube's query format (ADR 0001): measures, dimensions, time dimensions, filters, order and limit over its Feedback Dataset's fields. Every field must come from the field catalog (`GET /api/v3/charts/fields`), named with its data-source prefix. Display settings are separate (`config`). Refused with **422** (`invalid_params` names each problem): a field that is not in the catalog; Cube options the app does not use (`ungrouped`, `segments`, `renewQuery`, `joinHints`, `total`, `compareDateRange`); a `timezone` (every range is read in the organization's display time zone); more than 15 fields across `measures`, `dimensions` and `timeDimensions`; more than 25 filter conditions or filters nested deeper than three levels; a date range that is not a preset, `all-time` or two ISO calendar dates; on a chart grouped by time alone, a date range that spans more than 10,000 buckets of its `granularity` (code `limit_exceeded`). - `measures` string[] - `dimensions` string[] - `timeDimensions` object[] - `dimension` string, required: A field of kind `timeDimension`. - `granularity` 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' - `dateRange` union: A date range on a time dimension: a named preset from the field catalog's `datePresets` (`last 7 days`, `this month`, …), `all-time` (no range), or a pair of ISO calendar dates `[from, to]`, both inclusive, `from` not after `to`. Every range is read in the organization's display time zone; a `timezone` cannot be supplied. Charts saved before ranges were limited to presets may hold a relative range Cube reads itself (`last 3 months`, `this week`). Such a chart still renders and can be previewed, within the bucket limit below, and can be saved with that same range kept; a new chart, or an update to another range, must use a preset or a pair. A chart grouped by time alone (one time dimension with a `granularity`, no other dimensions) gets one row per bucket in its range, empty or not, so its range may span at most 10,000 buckets: about 13 months by the hour, or 27 years by the day. A wider range is refused with **422** `limit_exceeded`; use a coarser granularity or a shorter range. An older chart's relative range is measured back from now (`last 999 years` spans 999 years). Every preset fits at every granularity, and a chart with other dimensions returns only its real rows, so it is not limited. - … - `filters` ChartQueryFilter[] - union: A filter: either one condition on a field, or an `and` / `or` group of filters. Filters nest at most three levels: a group, a group inside it, and conditions inside that. A chart query holds at most 25 conditions in all. - … - `order` union: Sort order: `[field, direction]` pairs, or an object mapping a field to its direction. At most 10 entries. - array[] - … - object - `limit` integer - `offset` integer - `config` ChartConfig, required: Display settings, kept apart from the chart query. Every key is optional; each applies to the chart types named in its description and is ignored by the others. - `barOrientation` 'vertical' | 'horizontal': Bar charts. Defaults to `vertical`. - `pieDisplay` 'pie' | 'breakdown': Pie charts. Defaults to `pie`. - `areaDisplay` 'filled' | 'line': Area charts. Defaults to `filled`. - `matrixCellValue` 'percent' | 'count' | 'both': Matrix charts. Defaults to `percent`. - `matrixColorScale` boolean: Matrix charts. Defaults to `true`. - `matrixShowTotals` boolean: Matrix charts. Defaults to `false`. - `matrixTranspose` boolean: Matrix charts. Swaps rows and columns on screen; the query is unchanged. - `colors` string[] - `xAxisLabel` string - `yAxisLabel` string - `showLegend` boolean - `legendPosition` 'top' | 'bottom' | 'left' | 'right' - `stacked` boolean - `showGrid` boolean - `showValues` boolean - `numberFormat` string - `dateFormat` string - `prefix` string - `suffix` string - `creator` object, nullable, required: Who created the chart, for display only; `null` once that user is gone. - `name` string, required - `dashboards` object[], required: The dashboards that hold the chart, by name. - `id` string, cuid2, required - `name` string, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required: Changes on every rename, save and widget change. Send it back on a full update to be told if the dashboard changed in between. ## Other responses - `400`: Bad Request — malformed JSON, invalid query/body/params, duplicate name, or unsupported field. - `401`: Not authenticated (no valid session or API key). - `403`: Forbidden. `code: forbidden` when the caller has no access to the workspace, the Feedback Dataset or the resource (which may also not exist; 404 is not used, to avoid leaking existence). `code: dashboards_plan_required` when the caller is authorized but the organization does not have the Dashboards add-on or a license that includes it — checked after authorization, so a caller without access never learns the organization's plan. - `429`: Rate limit exceeded. - `500`: Internal Server Error. ## Changes - **2026-10-28** `84820a01e550`: 1 info - endpoint added [Operation history](https://skmtc.dev/formbricks/apis/formbricks-api-v3/changes/api/v3/dashboards/:dashboardId/get.md) --- [API](https://skmtc.dev/formbricks/apis/formbricks-api-v3.md) - [All operations](https://skmtc.dev/formbricks/apis/formbricks-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/formbricks/apis/formbricks-api-v3/revisions/25335c959a13?raw)