---
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`

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.

---

[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)