---
title: "Query Dashboard Data"
method: POST
path: "/v1/dashboards/{dashboardId}/query"
tags: ["Dashboards"]
---

# Query Dashboard Data

`POST /v1/dashboards/{dashboardId}/query`

Fetches computed data for all widgets on a dashboard, or for a provided subset of widget IDs. Request time range fields override widget defaults for this query only.

## Path parameters

- `dashboardId` string, required

## Request body

- DashboardQueryRequest — Query overrides for dashboard widgets. `startTime` and `endTime` must be provided together.
  - `startTime` string, date-time — ISO 8601 start time for the query range. Must be provided with `endTime`.
  - `endTime` string, date-time — ISO 8601 end time for the query range. Must be provided with `startTime`.
  - `granularity` 'thirty_minutes' | 'hour' | 'day' | 'week' | 'month' — Bucket size for computed widget data.
  - `widgetIds` string[] — Optional subset of widget IDs to query. If omitted, all widgets on the dashboard are queried.

## Response `200`

The computed data for the requested dashboard widgets.

- DashboardQueryResponse
  - `success` boolean, required — Indicates if the request was successful.
  - `data` object, required — The batch query payload.
    - `results` DashboardQueryResult[], required — Computed data or error details for each queried widget.
      - `widgetId` string, required — The id of the queried widget.
      - `status` 'ok' | 'error', required — Whether this widget's batch query succeeded.
      - `type` 'LINE' | 'AREA' | 'BAR' | 'STACKED_BAR' | 'TABLE' | 'BIG_NUMBER' — The visualization type of a widget.
      - `mode` 'TIME_SERIES' | 'DIMENSION_SERIES' — How a widget aggregates its lines. `TIME_SERIES` plots each configured line over time; `DIMENSION_SERIES` takes a single metric and splits it into one series per value of the widget's dimension. This is the widget's saved configuration — it does not by itself describe the shape of a query response (use `kind` on the query result for that).
      - `kind` 'TIME_SERIES' | 'DIMENSION' | 'BIG_NUMBER' | 'TABLE' — The shape of the data in this result, and the field you should branch on when reading it. `TIME_SERIES` and `DIMENSION` populate `series` (with `xAxis.type` `time` and `category` respectively); `BIG_NUMBER` populates `values`; `TABLE` populates `columns` and `rows`. It is derived from `type` and `mode`, so it can differ from `mode`. Present when `status` is `ok`.
      - `unit` 'COUNT' | 'PERCENT' | 'SCORE' | 'SECONDS' | 'USD' | 'MILLISECONDS' — The unit a widget's values are measured in.
      - `xAxis` object — Present for TIME_SERIES and DIMENSION results.
        - `type` 'time' | 'category', required — Axis type for the returned data.
      - `series` DashboardSeries[] — Present for TIME_SERIES and DIMENSION results.
        - `key` string, required — Stable key that uniquely identifies this series within the result. Use it to correlate series across queries or as a render key.
        - `name` string, required — Display name for the series.
        - `color` string, required — Display color for the series.
        - `lineId` string — The line id that produced this series, when applicable.
        - `points` DashboardSeriesPoint[], required — Points in this series.
          - `x` string, required — Time bucket start or category label.
          - `y` number, nullable, required — Numeric value for the series at this point, or null when no data is available.
      - `values` DashboardScalarValue[] — Present for BIG_NUMBER results.
        - `key` string, required — Stable key that uniquely identifies this value within the result.
        - `name` string, required — Display name for the value.
        - `color` string, required — Display color for the value.
        - `lineId` string — The line id that produced this value, when applicable.
        - `value` number, nullable, required — Scalar value, or null when no data is available.
      - `columns` object[] — Column definitions for TABLE results. The first column is the dimension (key `dimension`); the remaining columns are one per line, keyed by the line's name.
        - `key` string, required — Stable column key. Read each row's value for this column as `row[key]`.
        - `label` string, required — Display label for the column.
      - `rows` object[] — Present for TABLE results.
      - `error` object — Present only when `status` is `error`.
        - `code` 'QUERY_FAILED', required — Machine-readable query error code.
        - `message` string, required — Human-readable query error message.
  - `deprecated` boolean, required — Indicates if this endpoint is deprecated.

---

[API](https://skmtc.net/confident-ai/apis/confident-ai-metrics-api.md) · [All operations](https://skmtc.net/confident-ai/apis/confident-ai-metrics-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/confident-ai/confident-ai-metrics-api/revisions/95cdde71b65e/schema)