---
title: "Get Dashboard"
method: GET
path: "/api/v3/meta/bases/{baseId}/dashboards/{dashboardId}"
tags: ["Dashboards"]
---

# Get Dashboard

`GET /api/v3/meta/bases/{baseId}/dashboards/{dashboardId}`

## Request

- Base URL: `https://app.nocodb.com`
- URL: `https://app.nocodb.com/api/v3/meta/bases/{baseId}/dashboards/{dashboardId}`
- Auth: one of:
  - API key in header `xc-token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/nocodb/apis/nocodb-v3/docs/api/v3/meta/bases/:baseId/dashboards/:dashboardId/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve details of a specific dashboard. Pass `include=widgets` to include the dashboard's widgets in the response.

**Note**: Dashboard APIs are available on cloud-hosted **Enterprise** plans, and on licensed self-hosted deployments (**Business** plan and above).

## Path parameters

- `baseId` string, required
- `dashboardId` string, required

## Query parameters

- `include` string[]

## Response `200`

Dashboard details retrieved.

- DashboardGetResponse
  - `id` string, required: Unique identifier for the dashboard.
  - `title` string, required: Title of the dashboard.
  - `description` string, nullable: Description of the dashboard.
  - `base_id` string, required: Unique identifier for the base.
  - `workspace_id` string, required: Unique identifier for the workspace.
  - `created_at` string, date-time, required: Timestamp when the dashboard was created.
  - `updated_at` string, date-time, required: Timestamp when the dashboard was last updated.
  - `created_by` string: User ID of the dashboard creator.
  - `widgets` WidgetRead[]: List of widgets. Only included when the request passes `include=widgets`.
    - `id` string, required: Unique identifier for the widget.
    - `title` string, required: Title of the widget.
    - `description` string, nullable: Description of the widget.
    - `dashboard_id` string, required: Unique identifier for the parent dashboard.
    - `type` 'chart' | 'metric' | 'gauge' | 'table' | 'pivot' | 'text' | 'iframe', required: Type of the widget. `gauge`, `table` and `pivot` widgets are returned here but cannot yet be created or updated through this API — create them in the dashboard editor.
    - `options` union: Widget configuration. Structure depends on widget type. The branches below cover `metric`, `text`, `iframe` and `chart` with `chart_type` pie, donut, bar, line or scatter. A `gauge`, `table` or `pivot` widget, or a chart with `chart_type: treemap`, is returned with an options shape that is not modelled here yet and matches the open branch instead.
      - WidgetOptionsMetric: Options for a metric widget (type=metric).
        - `data_source` 'table' | 'view' | 'filter': Data source type.
        - `metric` object: Metric aggregation configuration.
          - `type` 'count' | 'summary', required: 'count' counts all rows, 'summary' aggregates a column.
          - `field_id` string: Column to aggregate. Required when type is 'summary'.
          - `aggregation` 'sum' | 'avg' | 'count' | 'min' | 'max', required: Aggregation function.
        - `appearance` object
          - `type` 'default' | 'filled' | 'coloured': Visual style variant.
          - `theme` 'gray' | 'red' | 'green' | 'yellow' | 'pink' | 'blue' | 'orange' | 'maroon' | 'purple': Color theme.
      - WidgetOptionsPieChart: Options for a pie chart widget (type=chart, chart_type=pie).
        - `chart_type` 'pie', required
        - `data_source` 'table' | 'view' | 'filter'
        - `data` object
          - `category` object
            - `field_id` string, required: Column to group by.
            - `order_by` 'default' | 'asc' | 'desc'
            - `category_limit` number: Max categories (10-50).
            - `include_empty_records` boolean
            - `include_others` boolean: Aggregate remaining into 'Others'.
          - `value` object
            - `type` 'count' | 'summary', required
            - `field_id` string: Column to aggregate. Required when type is 'summary'.
            - `aggregation` string: Aggregation function. Required when type is 'summary'.
        - `appearance` object
          - `size` 'small' | 'medium' | 'large'
          - `show_count_in_legend` boolean
          - `show_percentage_on_chart` boolean
          - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
          - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
          - `custom_color_schema` object[]
            - `color` string
            - `label` string
      - WidgetOptionsDonutChart: Options for a donut chart widget (type=chart, chart_type=donut). Same structure as pie chart.
        - `chart_type` 'donut', required
        - `data_source` 'table' | 'view' | 'filter'
        - `data` object
          - `category` object
            - `field_id` string, required
            - `order_by` 'default' | 'asc' | 'desc'
            - `category_limit` number
            - `include_empty_records` boolean
            - `include_others` boolean
          - `value` object
            - `type` 'count' | 'summary', required
            - `field_id` string
            - `aggregation` string
        - `appearance` object
          - `size` 'small' | 'medium' | 'large'
          - `show_count_in_legend` boolean
          - `show_percentage_on_chart` boolean
          - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
          - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
          - `custom_color_schema` object[]
            - `color` string
            - `label` string
      - WidgetOptionsBarChart: Options for a bar chart widget (type=chart, chart_type=bar).
        - `chart_type` 'bar', required
        - `data_source` 'table' | 'view' | 'filter'
        - `data` object
          - `x_axis` object: X-axis (category) configuration.
            - `field_id` string, required: X-axis grouping field.
            - `sort_by` 'x_axis' | 'y_axis': Sort by x-axis labels or y-axis values.
            - `order_by` 'default' | 'asc' | 'desc'
            - `include_empty_records` boolean
            - `include_others` boolean
            - `category_limit` number: Max categories (10-50).
          - `y_axis` object: Y-axis (value) configuration.
            - `start_at_zero` boolean
            - `fields` object[]: Fields to aggregate on the y-axis.
              - …
            - `group_by` string, nullable: Optional secondary grouping field ID.
        - `appearance` object
          - `size` 'small' | 'medium' | 'large'
          - `show_count_in_legend` boolean
          - `show_value_in_chart` boolean
          - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
          - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
      - WidgetOptionsLineChart: Options for a line chart widget (type=chart, chart_type=line). Same data structure as bar chart with additional line-specific appearance options.
        - `chart_type` 'line', required
        - `data_source` 'table' | 'view' | 'filter'
        - `data` object
          - `x_axis` object
            - `field_id` string, required
            - `sort_by` 'x_axis' | 'y_axis'
            - `order_by` 'default' | 'asc' | 'desc'
            - `include_empty_records` boolean
            - `include_others` boolean
            - `category_limit` number
          - `y_axis` object
            - `start_at_zero` boolean
            - `fields` object[]
              - …
            - `group_by` string, nullable
        - `appearance` object
          - `size` 'small' | 'medium' | 'large'
          - `smooth_lines` boolean: Smooth curve vs straight line segments.
          - `plot_data_points` boolean: Show dots at data points.
          - `show_count_in_legend` boolean
          - `show_value_in_chart` boolean
          - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
          - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
      - WidgetOptionsScatter: Options for a scatter plot widget (type=chart, chart_type=scatter). Same data structure as bar chart.
        - `chart_type` 'scatter', required
        - `data_source` 'table' | 'view' | 'filter'
        - `data` object
          - `x_axis` object
            - `field_id` string, required
            - `sort_by` 'x_axis' | 'y_axis'
            - `order_by` 'default' | 'asc' | 'desc'
            - `include_empty_records` boolean
            - `include_others` boolean
            - `category_limit` number
          - `y_axis` object
            - `start_at_zero` boolean
            - `fields` object[]
              - …
            - `group_by` string, nullable
        - `appearance` object
          - `size` 'small' | 'medium' | 'large'
          - `show_count_in_legend` boolean
          - `show_value_in_chart` boolean
          - `legend_position` 'top' | 'right' | 'bottom' | 'left' | 'none'
          - `color_schema` 'default' | 'classic' | 'vibrant' | 'pastel' | 'earth' | 'monoBlue' | 'custom'
      - WidgetOptionsText: Options for a text widget (type=text). Formatting is nested inside appearance.
        - `content` string: Text content (plain text or markdown).
        - `type` 'markdown' | 'text': Text rendering mode.
        - `appearance` object
          - `formatting` object: Text formatting options.
            - `horizontal_align` 'flex-start' | 'center' | 'flex-end'
            - `vertical_align` 'flex-start' | 'center' | 'flex-end'
            - `bold` boolean
            - `italic` boolean
            - `underline` boolean
            - `strikethrough` boolean
          - `font` object: Font settings (only for type=text).
            - `family` string
            - `weight` 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
            - `size` number: Font size in pixels.
            - `line_height` number: Line height multiplier.
          - `color` string: Hex color (only for type=text).
      - WidgetOptionsIframe: Options for an iframe widget (type=iframe).
        - `url` string: URL to embed.
        - `allow_fullscreen` boolean: Whether to allow fullscreen.
      - object: Options for a widget type whose shape is not modelled above.
    - `order` number, nullable: Display order of the widget.
    - `position` object, nullable: Position and size of the widget on the dashboard grid.
      - `x` number: Column position of the widget on the dashboard grid (0-indexed, left to right). e.g. 0 means the first column, 6 means starting at the 7th column.
      - `y` number: Row position of the widget on the dashboard grid (0-indexed, top to bottom). e.g. 0 means the first row, 4 means starting at the 5th row.
      - `w` number: Width of the widget in grid columns. e.g. 6 means the widget spans 6 columns (half of a 12-column grid).
      - `h` number: Height of the widget in grid rows. e.g. 4 means the widget spans 4 rows tall.
    - `table_id` string, nullable: Unique identifier for the associated table.
    - `view_id` string, nullable: Unique identifier for the associated view.
    - `error` boolean: Whether the widget has a configuration error.
    - `created_at` string, date-time, required: Timestamp when the widget was created.
    - `updated_at` string, date-time, required: Timestamp when the widget was last updated.

## Other responses

- `422`: Dashboard not found.
- `500`: Server error.

---

[API](https://skmtc.dev/nocodb/apis/nocodb-v3.md) - [All operations](https://skmtc.dev/nocodb/apis/nocodb-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/nocodb/apis/nocodb-v3/revisions/62a735aaf849?raw)