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

# Query Widget Data

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

## Request

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

Fetches computed data for one widget. Request time range fields override widget defaults for this query only.

## Path parameters

- `dashboardId` string, required
- `widgetId` string, required

## Request body

- DashboardWidgetQueryRequest: Query overrides for a single widget. `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.

## Response `200`

The computed data for the requested widget.

- DashboardWidgetQueryResponse
  - `success` boolean, required: Indicates if the request was successful.
  - `data` DashboardWidgetData, required: Computed data for a dashboard widget. The `kind` field indicates which shape-specific fields are populated.
    - `widgetId` string, required: The id of the queried widget.
    - `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', required: The shape of the data in this response, 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` — e.g. a `DIMENSION_SERIES` widget displayed as a `TABLE` returns `kind: TABLE`.
    - `unit` 'COUNT' | 'PERCENT' | 'SCORE' | 'SECONDS' | 'USD' | 'MILLISECONDS': The unit a widget's values are measured in.
    - `xAxis` object: Present for TIME_SERIES and DIMENSION data.
      - `type` 'time' | 'category', required: Axis type for the returned data.
    - `series` DashboardSeries[]: Present for TIME_SERIES and DIMENSION data.
      - `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 data.
      - `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 data. 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 data.
  - `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/widgets/:widgetId/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)