Skip to main content
PATCH
/
dashboards
/
widgets
/
{id}
cURL
curl --request PATCH \
  --url https://api.cekura.ai/dashboards/widgets/{id}/ \
  --header 'Content-Type: application/json' \
  --header 'X-CEKURA-API-KEY: <api-key>' \
  --data '
{
  "dashboard": 123,
  "name": "<string>",
  "filters": {
    "field": "<string>",
    "op": "eq",
    "value": "<unknown>",
    "operator": "and",
    "conditions": [
      "<unknown>"
    ]
  },
  "chart_type": "line",
  "data_type": "numeric",
  "field": "",
  "metric": 123,
  "time_period": "hour",
  "aggregation_function": "count",
  "group_by": "<unknown>",
  "metadata": "<unknown>"
}
'
{
  "chart_type": "line",
  "id": 123,
  "dashboard": 123,
  "name": "<string>",
  "filters": {
    "field": "<string>",
    "op": "eq",
    "value": "<unknown>",
    "operator": "and",
    "conditions": [
      "<unknown>"
    ]
  },
  "effective_filters": {
    "field": "<string>",
    "op": "eq",
    "value": "<unknown>",
    "operator": "and",
    "conditions": [
      "<unknown>"
    ]
  },
  "data_type": "numeric",
  "field": "",
  "metric": 123,
  "metric_name": "<string>",
  "time_period": "hour",
  "aggregation_function": "count",
  "group_by": "<unknown>",
  "metadata": "<unknown>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
X-CEKURA-API-KEY
string
header
required

API Key Authentication. It should be included in the header of each request.

Path Parameters

​
id
string
required

Body

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.
​
dashboard
integer | null

Dashboard this widget belongs to

​
name
string | null

Optional name/title for the widget

Maximum string length: 255
​
filters
object

Filter conditions to scope the data. See the Dashboards guide for supported fields, operators, and syntax.

Examples:
{
  "field": "success",
  "op": "eq",
  "value": true
}
{
  "operator": "and",
  "conditions": [
    {
      "field": "timestamp",
      "op": "gte",
      "value": "today-7d"
    },
    {
      "field": "duration",
      "op": "gte",
      "value": 60
    }
  ]
}
​
chart_type
enum<string>

Type of chart to display

  • line - Line
  • bar - Bar
  • pie - Pie
  • stat - Stat
Available options:
line,
bar,
pie,
stat
​
data_type
enum<string> | null

Data type of the field being plotted (optional, can be inferred)

  • numeric - Numeric
  • boolean - Boolean
  • string - String
  • datetime - DateTime
  • dynamic - Dynamic
Available options:
numeric,
boolean,
string,
datetime,
dynamic,
,
null
​
field
string
default:""

Field name to plot. See the Dashboards guide for available fields, valid chart types, and aggregation combinations.

Maximum string length: 255
Examples:

"duration"

"success"

"call_ended_reason"

"metric_evaluations.value"

"metadata.region"

​
metric
integer | null

Metric to use when field is 'metric_evaluations.value'

​
time_period
enum<string> | null

Time period for aggregation (for bar charts)

  • hour - Hour
  • day - Day
  • week - Week
  • month - Month
Available options:
hour,
day,
week,
month,
,
null
​
aggregation_function
enum<string> | null

Aggregation function to apply (for bar charts)

  • count - Count
  • sum - Sum
  • avg - Average
  • min - Minimum
  • max - Maximum
Available options:
count,
sum,
avg,
min,
max,
,
null
​
group_by
any | null

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
any | null

Frontend metadata (e.g., position, size, styling)

Response

200 - application/json

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.
​
chart_type
enum<string>
required

Type of chart to display

  • line - Line
  • bar - Bar
  • pie - Pie
  • stat - Stat
Available options:
line,
bar,
pie,
stat
​
id
integer
​
dashboard
integer | null

Dashboard this widget belongs to

​
name
string | null

Optional name/title for the widget

Maximum string length: 255
​
filters
object

Filter conditions to scope the data. See the Dashboards guide for supported fields, operators, and syntax.

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
object

Merged filters from dashboard and widget (read-only). Can be used with the call logs API filters_v2 parameter.

Examples:
{
  "field": "success",
  "op": "eq",
  "value": true
}
{
  "operator": "and",
  "conditions": [
    {
      "field": "timestamp",
      "op": "gte",
      "value": "today-7d"
    },
    {
      "field": "duration",
      "op": "gte",
      "value": 60
    }
  ]
}
​
data_type
enum<string> | null

Data type of the field being plotted (optional, can be inferred)

  • numeric - Numeric
  • boolean - Boolean
  • string - String
  • datetime - DateTime
  • dynamic - Dynamic
Available options:
numeric,
boolean,
string,
datetime,
dynamic,
,
null
​
field
string
default:""

Field name to plot. See the Dashboards guide for available fields, valid chart types, and aggregation combinations.

Maximum string length: 255
Examples:

"duration"

"success"

"call_ended_reason"

"metric_evaluations.value"

"metadata.region"

​
metric
integer | null

Metric to use when field is 'metric_evaluations.value'

​
metric_name
string

Name of the metric (if metric is set)

​
time_period
enum<string> | null

Time period for aggregation (for bar charts)

  • hour - Hour
  • day - Day
  • week - Week
  • month - Month
Available options:
hour,
day,
week,
month,
,
null
​
aggregation_function
enum<string> | null

Aggregation function to apply (for bar charts)

  • count - Count
  • sum - Sum
  • avg - Average
  • min - Minimum
  • max - Maximum
Available options:
count,
sum,
avg,
min,
max,
,
null
​
group_by
any | null

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
any | null

Frontend metadata (e.g., position, size, styling)

​
created_at
string<date-time> | null

When the widget was created

​
updated_at
string<date-time> | null

When the widget was last updated