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

# Query Dashboard Data

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

## Request

- Base URL: `https://api.confident-ai.com`
- URL: `https://api.confident-ai.com/v1/dashboards/{dashboardId}/query`
- Auth: none declared
- TypeScript: <https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/docs/v1/dashboards/:dashboardId/query/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Changes

> 54 revisions in range; 3 not diffed.

- **2026-06-30** `c5abbfd34161`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/changes/v1/dashboards/:dashboardId/query/post.md)

---

[API](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api.md) - [All operations](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/revisions/95cdde71b65e?raw)