> ## Documentation Index > Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Widget > Update a dashboard widget ## OpenAPI ````yaml patch /dashboards/widgets/{id}/ openapi: 3.1.0 info: title: Cekura API version: v1 description: >- Complete API documentation for the Cekura platform. This API provides endpoints for testing, observing, and evaluating AI voice agents — including managing agents, running evaluators, defining metrics, and analyzing call quality. servers: - url: https://api.cekura.ai security: [] paths: /dashboards/widgets/{id}/: patch: tags: - dashboards description: Update a dashboard widget operationId: dashboards-widgets-partial-update parameters: - in: path name: id schema: type: string required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedWidget' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedWidget' multipart/form-data: schema: $ref: '#/components/schemas/PatchedWidget' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Widget' description: '' security: - api_key: [] components: schemas: PatchedWidget: type: object description: >- 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=`. - `effective_filters` (read-only): merged dashboard + widget filters — useful for debugging. properties: id: type: integer readOnly: true dashboard: type: - integer - 'null' description: Dashboard this widget belongs to name: type: - string - 'null' description: Optional name/title for the widget maxLength: 255 filters: type: - object - 'null' description: >- Filter conditions to scope the data. See the [Dashboards guide](https://docs.cekura.ai/documentation/guides/dashboards#filters) for supported fields, operators, and syntax. properties: field: type: string description: Field name to filter on examples: - success - duration - timestamp - metadata.region - metric_evaluations.value op: type: string enum: - eq - neq - gt - gte - lt - lte - contains - startswith - endswith - in - isnull - regex description: Comparison operator value: description: >- Value to compare against. Type depends on the field and operator. operator: type: string enum: - and - or - same_row description: Logical operator to combine conditions conditions: type: array description: List of filter conditions or nested groups items: {} examples: - field: success op: eq value: true - operator: and conditions: - field: timestamp op: gte value: today-7d - field: duration op: gte value: 60 effective_filters: type: object description: >- Merged filters from dashboard and widget (read-only). Can be used with the call logs API filters_v2 parameter. properties: field: type: string description: Field name to filter on examples: - success - duration - timestamp - metadata.region - metric_evaluations.value op: type: string enum: - eq - neq - gt - gte - lt - lte - contains - startswith - endswith - in - isnull - regex description: Comparison operator value: description: >- Value to compare against. Type depends on the field and operator. operator: type: string enum: - and - or - same_row description: Logical operator to combine conditions conditions: type: array description: List of filter conditions or nested groups items: {} examples: - field: success op: eq value: true - operator: and conditions: - field: timestamp op: gte value: today-7d - field: duration op: gte value: 60 readOnly: true chart_type: enum: - line - bar - pie - stat type: string x-spec-enum-id: 458699e47c376d15 description: |- Type of chart to display * `line` - Line * `bar` - Bar * `pie` - Pie * `stat` - Stat data_type: enum: - numeric - boolean - string - datetime - dynamic - '' - null type: - string - 'null' x-spec-enum-id: 553dbfa7e4c5fb6a description: |- Data type of the field being plotted (optional, can be inferred) * `numeric` - Numeric * `boolean` - Boolean * `string` - String * `datetime` - DateTime * `dynamic` - Dynamic field: type: string description: >- 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. examples: - duration - success - call_ended_reason - metric_evaluations.value - metadata.region default: '' maxLength: 255 metric: type: - integer - 'null' description: Metric to use when field is 'metric_evaluations.value' metric_name: type: string readOnly: true description: Name of the metric (if metric is set) time_period: enum: - hour - day - week - month - '' - null type: - string - 'null' x-spec-enum-id: c3b53047d634938d description: |- Time period for aggregation (for bar charts) * `hour` - Hour * `day` - Day * `week` - Week * `month` - Month aggregation_function: enum: - count - sum - avg - min - max - p50 - p95 - p99 - '' - null type: - string - 'null' x-spec-enum-id: be3fac57dbd138ef description: |- 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: oneOf: - {} - type: 'null' description: >- Optional group-by configuration. Field group: `{"type": "field", "field": "agent.id"}`. Time bucket: `{"type": "bucket", "interval": 3600000}` (interval in milliseconds). Leave null or empty for no grouping. metadata: oneOf: - {} - type: 'null' description: Frontend metadata (e.g., position, size, styling) created_at: type: - string - 'null' format: date-time readOnly: true description: When the widget was created updated_at: type: - string - 'null' format: date-time readOnly: true description: When the widget was last updated Widget: type: object description: >- 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=`. - `effective_filters` (read-only): merged dashboard + widget filters — useful for debugging. properties: id: type: integer readOnly: true dashboard: type: - integer - 'null' description: Dashboard this widget belongs to name: type: - string - 'null' description: Optional name/title for the widget maxLength: 255 filters: type: - object - 'null' description: >- Filter conditions to scope the data. See the [Dashboards guide](https://docs.cekura.ai/documentation/guides/dashboards#filters) for supported fields, operators, and syntax. properties: field: type: string description: Field name to filter on examples: - success - duration - timestamp - metadata.region - metric_evaluations.value op: type: string enum: - eq - neq - gt - gte - lt - lte - contains - startswith - endswith - in - isnull - regex description: Comparison operator value: description: >- Value to compare against. Type depends on the field and operator. operator: type: string enum: - and - or - same_row description: Logical operator to combine conditions conditions: type: array description: List of filter conditions or nested groups items: {} examples: - field: success op: eq value: true - operator: and conditions: - field: timestamp op: gte value: today-7d - field: duration op: gte value: 60 effective_filters: type: object description: >- Merged filters from dashboard and widget (read-only). Can be used with the call logs API filters_v2 parameter. properties: field: type: string description: Field name to filter on examples: - success - duration - timestamp - metadata.region - metric_evaluations.value op: type: string enum: - eq - neq - gt - gte - lt - lte - contains - startswith - endswith - in - isnull - regex description: Comparison operator value: description: >- Value to compare against. Type depends on the field and operator. operator: type: string enum: - and - or - same_row description: Logical operator to combine conditions conditions: type: array description: List of filter conditions or nested groups items: {} examples: - field: success op: eq value: true - operator: and conditions: - field: timestamp op: gte value: today-7d - field: duration op: gte value: 60 readOnly: true chart_type: enum: - line - bar - pie - stat type: string x-spec-enum-id: 458699e47c376d15 description: |- Type of chart to display * `line` - Line * `bar` - Bar * `pie` - Pie * `stat` - Stat data_type: enum: - numeric - boolean - string - datetime - dynamic - '' - null type: - string - 'null' x-spec-enum-id: 553dbfa7e4c5fb6a description: |- Data type of the field being plotted (optional, can be inferred) * `numeric` - Numeric * `boolean` - Boolean * `string` - String * `datetime` - DateTime * `dynamic` - Dynamic field: type: string description: >- 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. examples: - duration - success - call_ended_reason - metric_evaluations.value - metadata.region default: '' maxLength: 255 metric: type: - integer - 'null' description: Metric to use when field is 'metric_evaluations.value' metric_name: type: string readOnly: true description: Name of the metric (if metric is set) time_period: enum: - hour - day - week - month - '' - null type: - string - 'null' x-spec-enum-id: c3b53047d634938d description: |- Time period for aggregation (for bar charts) * `hour` - Hour * `day` - Day * `week` - Week * `month` - Month aggregation_function: enum: - count - sum - avg - min - max - p50 - p95 - p99 - '' - null type: - string - 'null' x-spec-enum-id: be3fac57dbd138ef description: |- 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: oneOf: - {} - type: 'null' description: >- Optional group-by configuration. Field group: `{"type": "field", "field": "agent.id"}`. Time bucket: `{"type": "bucket", "interval": 3600000}` (interval in milliseconds). Leave null or empty for no grouping. metadata: oneOf: - {} - type: 'null' description: Frontend metadata (e.g., position, size, styling) created_at: type: - string - 'null' format: date-time readOnly: true description: When the widget was created updated_at: type: - string - 'null' format: date-time readOnly: true description: When the widget was last updated required: - chart_type securitySchemes: api_key: type: apiKey name: X-CEKURA-API-KEY in: header description: >- API Key Authentication. It should be included in the header of each request. ````