---
title: "Preview widget data"
method: POST
path: "/dashboards/widgets/preview_data/"
tags: ["dashboards"]
---

# Preview widget data

`POST /dashboards/widgets/preview_data/`

## Request

- Base URL: `https://api.cekura.ai`
- URL: `https://api.cekura.ai/dashboards/widgets/preview_data/`
- Auth: one of:
  - API key in header `X-CEKURA-API-KEY`
  - HTTP bearer
  - HTTP bearer
  - API key in header `X-VOCERA-SHAREABLE-LINK-TOKEN`
  - HTTP bearer

Preview widget data without saving.

## Query parameters

- `timezone` string

## Request body

- Widget: Widget configuration. Key rules: - `line` / `pie`: set `field` only (e.g. `"duration"`, `"call_ended_reason"`). No aggregation needed. - `bar`: set `field` + `aggregation_function` (e.g. `"count"`) + `time_period` (e.g. `"day"`). - `stat`: leave `field` empty — returns total_calls, success_rate, avg_duration, p95_latency. - `field = "metric_evaluations.value"`: `metric` (integer metric ID) is **required**. Get valid IDs from `GET /test_framework/v1/metrics?agent_id=<id>`. - `effective_filters` (read-only): merged dashboard + widget filters — useful for debugging.
  - `id` integer
  - `dashboard` integer, nullable: Dashboard this widget belongs to
  - `name` string, nullable: Optional name/title for the widget
  - `filters` object, nullable: Filter conditions to scope the data. See the [Dashboards guide](https://docs.cekura.ai/documentation/guides/dashboards#filters) for supported fields, operators, and syntax.
    - `field` string: Field name to filter on
    - `op` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'startswith' | 'endswith' | 'in' | 'isnull' | 'regex': Comparison operator
    - `value` unknown
    - `operator` 'and' | 'or' | 'same_row': Logical operator to combine conditions
    - `conditions` unknown[]: List of filter conditions or nested groups
      - unknown
  - `effective_filters` object: Merged filters from dashboard and widget (read-only). Can be used with the call logs API filters_v2 parameter.
    - `field` string: Field name to filter on
    - `op` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'startswith' | 'endswith' | 'in' | 'isnull' | 'regex': Comparison operator
    - `value` unknown
    - `operator` 'and' | 'or' | 'same_row': Logical operator to combine conditions
    - `conditions` unknown[]: List of filter conditions or nested groups
      - unknown
  - `chart_type` 'line' | 'bar' | 'pie' | 'stat', required: Type of chart to display * `line` - Line * `bar` - Bar * `pie` - Pie * `stat` - Stat
  - `data_type` 'numeric' | 'boolean' | 'string' | 'datetime' | 'dynamic' | '' | 'null', nullable: Data type of the field being plotted (optional, can be inferred) * `numeric` - Numeric * `boolean` - Boolean * `string` - String * `datetime` - DateTime * `dynamic` - Dynamic
  - `field` string: Field name to plot. See the [Dashboards guide](https://docs.cekura.ai/documentation/guides/dashboards#supported-fields) for available fields, valid chart types, and aggregation combinations.
  - `metric` integer, nullable: Metric to use when field is 'metric_evaluations.value'
  - `metric_name` string: Name of the metric (if metric is set)
  - `time_period` 'hour' | 'day' | 'week' | 'month' | '' | 'null', nullable: Time period for aggregation (for bar charts) * `hour` - Hour * `day` - Day * `week` - Week * `month` - Month
  - `aggregation_function` 'count' | 'sum' | 'avg' | 'min' | 'max' | 'p50' | 'p95' | 'p99' | '' | 'null', nullable: Aggregation function to apply (for bar charts) * `count` - Count * `sum` - Sum * `avg` - Average * `min` - Minimum * `max` - Maximum * `p50` - 50th Percentile (Median) * `p95` - 95th Percentile * `p99` - 99th Percentile
  - `group_by` unknown
  - `metadata` unknown
  - `created_at` string, date-time, nullable: When the widget was created
  - `updated_at` string, date-time, nullable: When the widget was last updated

## Response `200`

- WidgetDataResponse
  - `widget_id` integer, required
  - `field_name` string, required
  - `chart_type` string, required
  - `data` object[], required: Chart data. Format depends on `chart_type`: **Line chart:** `[{id, timestamp, value}, ...]` **Bar chart:** `[{time_interval, value, sample_count}, ...]` **Enum daily share:** `[{time_interval, group, value, selected_calls, total_calls, evaluated_calls}, ...]`, where `value` is the selected enum value's percentage of total filtered calls. **Pie chart:** `[{label, value, percentage}, ...]` See the [Dashboards guide](https://docs.cekura.ai/documentation/guides/dashboards#chart-output-formats) for full examples.
  - `aggregation_function` string, nullable, required
  - `time_period` string, nullable, required
  - `group_by` unknown, required
  - `can_group_by` boolean
  - `metadata` object, required: Additional metadata about the plotted data. See the [Dashboards guide](https://docs.cekura.ai/documentation/guides/dashboards#widget-data) for details.
    - `display_name` string: Human-readable name of the field
    - `data_type` 'numeric' | 'boolean' | 'string' | 'datetime' | 'dynamic' | 'percentage': Resolved data type of the field
    - `filter_value` unknown
    - `series_dimension` 'enum_value': Server-supplied series dimension for enum daily shares.
    - `normalization` 'total_calls': Denominator used for enum daily shares.
  - `warning` WidgetDataWarning
    - `code` string, required
    - `message` string, required

## Changes

- **2026-11-03** `a6fb6a739212`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/dashboards/widgets/preview_data/post.md)

---

[API](https://skmtc.dev/cekura/apis/cekura-api.md) - [All operations](https://skmtc.dev/cekura/apis/cekura-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cekura/apis/cekura-api/revisions/a6fb6a739212?raw)