{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cekura-ai/json-schema/cekura-ai-dashboard-schema.json",
  "title": "Dashboard",
  "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/Dashboard",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "readOnly": true
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Name of the dashboard",
      "maxLength": 255
    },
    "project": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Project this dashboard belongs to"
    },
    "source": {
      "enum": [
        "call_logs",
        "runs"
      ],
      "type": "string",
      "x-spec-enum-id": "ddad6ce3969c508d",
      "description": "Dataset the widgets plot: `call_logs` (production calls, the default) or `runs` (simulation test runs). Set on create; it cannot be changed afterwards.\n\n* `call_logs` - Call Logs\n* `runs` - Runs"
    },
    "is_default": {
      "type": "boolean",
      "readOnly": true,
      "description": "Whether this is the project's default dashboard for its source."
    },
    "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": {}
        }
      }
    },
    "widgets": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Widget"
      },
      "readOnly": true
    },
    "widget_count": {
      "type": "string",
      "readOnly": true,
      "description": "Number of widgets in the dashboard"
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "readOnly": true,
      "description": "When the dashboard was created"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "readOnly": true,
      "description": "When the dashboard was last updated"
    }
  },
  "$defs": {
    "Widget": {
      "type": "object",
      "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.",
      "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"
      ]
    }
  }
}