---
title: "Query Ad-hoc Widget Data"
method: POST
path: "/v1/widgets/query"
tags: ["Dashboards"]
---

# Query Ad-hoc Widget Data

`POST /v1/widgets/query`

Computes widget data from a widget definition supplied inline, without creating a dashboard or saving a widget. Returns the same data shape as the dashboard widget query. Scoped to the project of the API key. At most 20 lines and a `topK.limit` of 100 are allowed, and an explicit query range may not exceed 366 days.

## Request body

- WidgetQueryRequest — An ad-hoc widget definition to compute, plus an optional query time range. `startTime` and `endTime` must be provided together and override the widget's own time fields for this query.
  - `widget` DashboardWidgetInput, required — A widget configuration to create or update. If layout is omitted, the server assigns a default grid position.
    - `name` string, required — The widget's name.
    - `description` string, nullable — An optional description of the widget.
    - `type` 'LINE' | 'AREA' | 'BAR' | 'STACKED_BAR' | 'TABLE' | 'BIG_NUMBER' — The visualization type of a widget.
    - `unit` 'COUNT' | 'PERCENT' | 'SCORE' | 'SECONDS' | 'USD' | 'MILLISECONDS' — The unit a widget's values are measured in.
    - `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).
    - `bucketMode` 'SERIES' | 'RANGE' — How a widget's data is bucketed over the query time range. `SERIES` splits the range into one bucket per `granularity` interval (a time series); `RANGE` aggregates the whole range into a single bucket (one total, as used by BIG_NUMBER widgets). Defaults to `SERIES` when omitted.
    - `dimension` 'project' | 'trace_name' | 'span_name' | 'model' | 'type' | 'thread_id' | 'test_case_id' | 'test_run_id' | 'end_user' | 'source' | 'annotator' | 'name' | 'error' | 'prompt_alias' | 'tag' | 'label' | 'evaluation_model' | 'prompt_version' | 'prompt_label' | 'prompt_commit_hash' | 'metadata' | 'classifier' — The dimension a widget breaks down by when mode is DIMENSION_SERIES.
    - `topK` DashboardTopK — Limits a dimension breakdown to the top K series.
      - `limit` integer — Maximum number of series to return. Defaults to 10.
      - `orderBy` 'count' | 'avg_latency' | 'p50_latency' | 'p90_latency' | 'p99_latency' | 'error_rate' | 'pass_rate' | 'failure_rate' | 'input_cost' | 'output_cost' | 'total_cost' | 'avg_cost' | 'input_tokens' | 'output_tokens' | 'total_tokens' | 'count_distinct_endUserId' | 'count_distinct_threadId' | 'count_distinct_model' | 'count_distinct_projectId' | 'count_distinct_error' | 'count_distinct_metadata' | 'error_count' | 'avg_score' | 'stddev_score' | 'avg_rating' | 'created_at' | 'start_time' | 'dimension' — The metric or column to order topK results by.
      - `direction` 'asc' | 'desc' — The sort direction for topK results.
    - `startTime` string, date-time, nullable — The start of the widget's custom time range, if set.
    - `endTime` string, date-time, nullable — The end of the widget's custom time range, if set.
    - `layout` DashboardLayout — A widget's position on the dashboard grid.
      - `x` number — The widget's left edge as a column index on the 12-column grid.
      - `y` number — The widget's top edge as a row index on the grid.
      - `w` number — The widget's width in grid columns.
      - `h` number — The widget's height in grid rows.
    - `lines` DashboardLineInput[], nullable — The series to show in the widget.
      - `name` string, required — The line's name.
      - `color` 'AMBER' | 'VIOLET' | 'EMERALD' | 'BLUE' | 'PINK' | 'CYAN' | 'ROSE' | 'LIME' | 'TEAL' | 'ORANGE' — The color of a line. If omitted or unrecognized, a color is auto-assigned from the palette.
      - `dataModel` 'TRACE' | 'SPAN' | 'LLM_SPAN' | 'AGENT_SPAN' | 'RETRIEVER_SPAN' | 'TOOL_SPAN' | 'CUSTOM_SPAN' | 'THREAD' | 'END_USER' | 'METRIC_DATA' | 'ANNOTATION' — The entity a line aggregates over.
      - `aggregation` 'COUNT' | 'ERROR_RATE' | 'PASS_RATE' | 'UNIQUE_END_USERS' | 'UNIQUE_THREADS' | 'UNIQUE_USERS' | 'UNIQUE_METADATA_VALUES' | 'AVG_LATENCY' | 'P50_LATENCY' | 'P90_LATENCY' | 'P99_LATENCY' | 'TOTAL_COST' | 'AVG_COST' | 'INPUT_COST' | 'OUTPUT_COST' | 'AVG_COST_PER_USER' | 'INPUT_TOKENS' | 'OUTPUT_TOKENS' | 'TOTAL_TOKENS' | 'ERROR_COUNT' | 'NEW_USERS' | 'RETENTION' | 'AVG_SCORE' | 'FAILURE_RATE' | 'AVG_RATING' — The aggregation applied to a line. The set of valid values depends on the line's dataModel.
      - `filters` DashboardFilterSet — A set of filter groups combined by a top-level operator.
        - `operator` 'AND' | 'OR', required — How filters or groups are combined.
        - `groups` DashboardFilterGroup[], required — The filter groups.
          - `operator` 'AND' | 'OR', required — How filters or groups are combined.
          - `filters` DashboardFilterRow[], required — The filter rows in this group.
            - `category` string, required — The property a filter row matches on (e.g. "Name", "User Id", "Model", "Metadata"). The set of valid values depends on the line's dataModel.
            - `condition` 'Is' | 'Is not' | 'Is equal to' | 'Does not equal' | 'Is less than' | 'Is equal or less than' | 'Is greater than' | 'Is equal or greater than' | 'Has' | 'Has not' | 'Contains' | 'Contains only' | 'Does not contain' | 'Has increased by more than' | 'Has increased by less than' | 'Has decreased by more than' | 'Has decreased by less than' | 'Has changed from', required — The comparison a filter row applies. Valid conditions depend on the category.
            - `value` union, required — The value to match against.
              - …
            - `key` string — The property key. Auto-populated from category when omitted; required for Metadata, Metric, and Classifier filters.
      - `extraQueryParams` DashboardLineExtraQueryParams, nullable — Advanced, per-line query parameters. Which keys take effect depends on the line's `dataModel`, and unrecognized keys are ignored. All values are strings. Most lines leave this `null`.
        - `spanType` 'LLM' | 'AGENT' | 'RETRIEVER' | 'TOOL' | 'CUSTOM' — For a `SPAN` line, restricts aggregation to a single span type. Not needed for the typed span models (`LLM_SPAN`, `AGENT_SPAN`, `RETRIEVER_SPAN`, `TOOL_SPAN`, `CUSTOM_SPAN`), which already imply their span type.
        - `metricMetadataKey` string — For span (`SPAN`, `LLM_SPAN`, `AGENT_SPAN`, `RETRIEVER_SPAN`, `TOOL_SPAN`, `CUSTOM_SPAN`), `TRACE`, and `THREAD` lines, the metadata field key whose numeric value is aggregated.
        - `category` 'SINGLE_TURN' | 'MULTI_TURN' | 'TEST_RUN' | 'TRACE' | 'SPAN' | 'LLM_SPAN' | 'AGENT_SPAN' | 'RETRIEVER_SPAN' | 'TOOL_SPAN' | 'CUSTOM_SPAN' | 'THREAD' — For a `METRIC_DATA` line, the entity category the metric is attached to.
        - `metricName` string — For a `METRIC_DATA` line, the name of the metric to aggregate.
        - `dataType` 'Traces' | 'Spans' | 'Threads' — For an `ANNOTATION` line, which annotated entity type to aggregate over.
        - `source` 'User' | 'Reviewer' — For an `ANNOTATION` line, whether to aggregate annotations left by end users or by reviewers.
  - `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 supplied widget.

- WidgetQueryResponse
  - `success` boolean, required — Indicates if the request was successful.
  - `data` WidgetQueryData, required — Computed data for an ad-hoc widget. The `kind` field indicates which shape-specific fields are populated.
    - `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 to 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`.
    - `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/versions/95cdde71b65e/schema)