Query Widget

POSThttps://api.confident-ai.com/v2/dashboards/{dashboardId}/widgets/{widgetId}/query

Computes the data behind one widget. A time range you send overrides the widget's own for this query only. Branch on data.kind to read the result: the widget's type and mode say how it is drawn, not how the payload is shaped.

POST/v2/dashboards/{dashboardId}/widgets/{widgetId}/query

curl -X POST "https://api.confident-ai.com/v2/dashboards/{dashboardId}/widgets/{widgetId}/query" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "startTime": "2025-01-01T00:00:00.000Z",
  "endTime": "2025-01-31T23:59:59.999Z",
  "granularity": "thirty_minutes"
}'

200

{
  "success": true,
  "data": {
    "widgetId": "<WIDGET-ID>",
    "type": "LINE",
    "mode": "TIME_SERIES",
    "data": {
      "kind": "BIG_NUMBER",
      "unit": "COUNT",
      "values": [
        {
          "key": "Traces",
          "name": "Traces",
          "color": "AMBER",
          "lineId": "<LINE-ID>",
          "value": 3814
        }
      ]
    }
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

dashboardIdstringRequired
The id of the dashboard the widget is on.
widgetIdstringRequired
The id of the widget.

Request body

startTimestring
The start of the range to compute over, as an ISO 8601 datetime. Must be sent together with endTime, and overrides each widget's own range for this query only.
endTimestring
The end of the range to compute over, as an ISO 8601 datetime. Must be sent together with startTime, and must be later than it.
granularityenum
The size of each bucket in computed widget data. Left unset, Confident AI picks one from the length of the query range.
Show 5 enum valuesHide 5 enum values
- thirty_minutes
- hour
- day
- week
- month

Response

Query Widget succeeded.

successboolean
Indicates if the request was successful.
dataobject
One widget's computed data, with the widget it came from.
Show 4 propertiesHide 4 properties
- widgetIdstring
  The id of the widget this result was computed for.
- typeenum | null
  The visualization a widget is drawn as. It is how the widget is displayed and does not by itself decide the shape of a query response — a TABLE widget returns tabular data whatever its mode is.
  Show 7 enum valuesHide 7 enum values
  - LINE
  - AREA
  - BAR
  - STACKED_BAR
  - GROUPED_BAR
  - TABLE
  - BIG_NUMBER
- modeenum | null
  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 — the shape of a query response is given by kind on the result.
  Show 2 enum valuesHide 2 enum values
  - TIME_SERIES
  - DIMENSION_SERIES
- dataobject | object | object | object
  A widget's computed data. Branch on kind to read it: Confident AI derives the shape from the widget's type and mode, so a DIMENSION_SERIES widget drawn as a TABLE returns TABLE data.
  Show 4 variantsHide 4 variants
  - Widget Big Number Dataobject
    The whole query range aggregated to one figure per line, as a BIG_NUMBER widget draws it.
    Show 3 propertiesHide 3 properties
    kindenum
    Marks the result as a set of headline figures.
    Show 1 enum valueHide 1 enum value
    BIG_NUMBER
    unitenum | null
    The unit a widget's values are measured in.
    Show 6 enum valuesHide 6 enum values
    COUNT
    PERCENT
    SCORE
    SECONDS
    USD
    MILLISECONDS
    valueslist of objects
    One figure per line on the widget.
    Show 5 propertiesHide 5 properties
    keystring
    A key that identifies this series within the result, unique across the result and stable between queries. Use it as a render key, or to line results up across queries.
    namestring
    The label to show for the series.
    colorenum
    The colour a line is drawn in, from the Confident AI palette. A line you create without one is assigned the next colour in the palette.
    Show 10 enum valuesHide 10 enum values
    AMBER
    VIOLET
    EMERALD
    BLUE
    PINK
    CYAN
    ROSE
    LIME
    TEAL
    ORANGE
    lineIdstring
    The id of the widget line this series was computed from, when one line produced it.
    valuenumber | null
    The aggregated value over the whole query range, or null when there was nothing to aggregate.
  - OR
  - Widget Time Series Dataobject
    Values bucketed over the query range, each point's x the start of its time bucket.
    Show 3 propertiesHide 3 properties
    kindenum
    Marks the result as series plotted against time.
    Show 1 enum valueHide 1 enum value
    TIME_SERIES
    unitenum | null
    The unit a widget's values are measured in.
    Show 6 enum valuesHide 6 enum values
    COUNT
    PERCENT
    SCORE
    SECONDS
    USD
    MILLISECONDS
    serieslist of objects
    One series per line, or per dimension value when the widget breaks its single line down.
    Show 5 propertiesHide 5 properties
    keystring
    A key that identifies this series within the result, unique across the result and stable between queries. Use it as a render key, or to line results up across queries.
    namestring
    The label to show for the series.
    colorenum
    The colour a line is drawn in, from the Confident AI palette. A line you create without one is assigned the next colour in the palette.
    Show 10 enum valuesHide 10 enum values
    AMBER
    VIOLET
    EMERALD
    BLUE
    PINK
    CYAN
    ROSE
    LIME
    TEAL
    ORANGE
    lineIdstring
    The id of the widget line this series was computed from, when one line produced it.
    pointslist of objects
    The series' points, ordered by time for TIME_SERIES data and by the order the dimension values were ranked in for DIMENSION data.
    Show 2 propertiesHide 2 properties
    xstring
    The point's position along the x axis: the start of the time bucket for TIME_SERIES data, the dimension value for DIMENSION data.
    ynumber | null
    The aggregated value at this point, or null when the bucket held nothing to aggregate.
  - OR
  - Widget Dimension Dataobject
    The whole query range aggregated per dimension value, as a DIMENSION_SERIES widget draws it.
    Show 3 propertiesHide 3 properties
    kindenum
    Marks the result as series plotted against a dimension.
    Show 1 enum valueHide 1 enum value
    DIMENSION
    unitenum | null
    The unit a widget's values are measured in.
    Show 6 enum valuesHide 6 enum values
    COUNT
    PERCENT
    SCORE
    SECONDS
    USD
    MILLISECONDS
    serieslist of objects
    One series per line, each point's x a value of the widget's dimension.
    Show 5 propertiesHide 5 properties
    keystring
    A key that identifies this series within the result, unique across the result and stable between queries. Use it as a render key, or to line results up across queries.
    namestring
    The label to show for the series.
    colorenum
    The colour a line is drawn in, from the Confident AI palette. A line you create without one is assigned the next colour in the palette.
    Show 10 enum valuesHide 10 enum values
    AMBER
    VIOLET
    EMERALD
    BLUE
    PINK
    CYAN
    ROSE
    LIME
    TEAL
    ORANGE
    lineIdstring
    The id of the widget line this series was computed from, when one line produced it.
    pointslist of objects
    The series' points, ordered by time for TIME_SERIES data and by the order the dimension values were ranked in for DIMENSION data.
    Show 2 propertiesHide 2 properties
    xstring
    The point's position along the x axis: the start of the time bucket for TIME_SERIES data, the dimension value for DIMENSION data.
    ynumber | null
    The aggregated value at this point, or null when the bucket held nothing to aggregate.
  - OR
  - Widget Table Dataobject
    The whole query range aggregated into a table, as a TABLE widget draws it.
    Show 3 propertiesHide 3 properties
    kindenum
    Marks the result as columns and rows.
    Show 1 enum valueHide 1 enum value
    TABLE
    columnslist of objects
    The table's columns: the widget's dimension first, under the key dimension, then one column per line.
    Show 2 propertiesHide 2 properties
    keystring
    The key each row holds this column's value under.
    labelstring
    The label to show in the column header.
    rowslist of objects
    One row per dimension value. Each row holds its values under the key of the column they belong to, and a value is null where the row had nothing to aggregate.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI