{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cekura-ai/json-schema/cekura-ai-widget-schema.json",
  "title": "Widget",
  "description": "Widget configuration. Key rules:\n- `line` / `pie`: set `field` only (e.g. `\"duration\"`, `\"call_ended_reason\"`). No aggregation needed.\n- `bar`: set `field` + `aggregation_function` (e.g. `\"count\"`) + `time_period` (e.g. `\"day\"`).\n- `stat`: leave `field` empty — returns total_calls, success_rate, avg_duration, p95_latency.\n- `field = \"metric_evaluations.value\"`: `metric` (integer metric ID) is **required**.\n  Get valid IDs from `GET /test_framework/v1/metrics?agent_id=<id>`.\n- `effective_filters` (read-only): merged dashboard + widget filters — useful for debugging.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cekura-ai-dashboards-api-openapi.yml#/components/schemas/Widget",
  "type": "object",
  "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"
        },
        "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": {}
        }
      }
    },
    "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"
        },
        "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": {}
        }
      },
      "readOnly": true
    },
    "chart_type": {
      "enum": [
        "line",
        "bar",
        "pie",
        "stat"
      ],
      "type": "string",
      "x-spec-enum-id": "458699e47c376d15",
      "description": "Type of chart to display\n\n* `line` - Line\n* `bar` - Bar\n* `pie` - Pie\n* `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)\n\n* `numeric` - Numeric\n* `boolean` - Boolean\n* `string` - String\n* `datetime` - DateTime\n* `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.",
      "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)\n\n* `hour` - Hour\n* `day` - Day\n* `week` - Week\n* `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)\n\n* `count` - Count\n* `sum` - Sum\n* `avg` - Average\n* `min` - Minimum\n* `max` - Maximum\n* `p50` - 50th Percentile (Median)\n* `p95` - 95th Percentile\n* `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"
  ]
}