{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/roark/json-schema/roark-analytics-query-schema.json",
  "title": "AnalyticsQuery",
  "description": "An aggregate query: one or more measures over a time window, optionally filtered, broken down and compared. GET /v1/analytics/schema lists the metrics, filters and breakdowns available.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/roark-analytics-api-openapi.yml#/components/schemas/AnalyticsQuery",
  "type": "object",
  "properties": {
    "measures": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "METRIC",
              "CONVERSATION",
              "UPTIME"
            ],
            "description": "METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes."
          },
          "metric": {
            "type": "string",
            "minLength": 1,
            "description": "The metric's slug (e.g. `task_completion`) or id. Required for METRIC."
          },
          "aggregation": {
            "type": "string",
            "enum": [
              "COUNT",
              "AVG",
              "MIN",
              "MAX",
              "SUM",
              "MEDIAN",
              "PERCENTILE",
              "PASS_RATE"
            ],
            "description": "Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations."
          },
          "percentile": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Required with PERCENTILE, e.g. 95."
          },
          "distinctBy": {
            "type": "string",
            "enum": [
              "NONE",
              "CALL"
            ],
            "description": "CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value."
          },
          "nestedAggregation": {
            "type": "string",
            "enum": [
              "COUNT",
              "AVG",
              "MIN",
              "MAX",
              "SUM",
              "MEDIAN",
              "PERCENTILE",
              "PASS_RATE"
            ],
            "description": "How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG."
          },
          "nestedAggregationPercentile": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "passOperator": {
            "type": "string",
            "enum": [
              "EQUALS",
              "NOT_EQUALS",
              "GREATER_THAN",
              "GREATER_THAN_OR_EQUAL_TO",
              "LESS_THAN",
              "LESS_THAN_OR_EQUAL_TO",
              "CONTAINS",
              "STARTS_WITH",
              "IS_SET",
              "IS_NOT_SET"
            ],
            "description": "PASS_RATE condition operator. Omit for a threshold metric: its own condition is used."
          },
          "passValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ],
            "description": "PASS_RATE condition value, e.g. 4 or \"resolved\"."
          },
          "breakdown": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "METRIC_PROPERTY",
                  "CALL_PROPERTY",
                  "AGENT_PROPERTY",
                  "DATASET"
                ]
              },
              "property": {
                "type": "string",
                "description": "The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY."
              }
            },
            "required": [
              "type"
            ],
            "description": "Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series."
          },
          "filters": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "METRIC_PROPERTY",
                    "CALL_PROPERTY",
                    "AGENT_PROPERTY",
                    "CALL_ID",
                    "MODALITY",
                    "DATASET",
                    "METRIC_VALUE"
                  ],
                  "description": "What the filter narrows on. GET /v1/analytics/schema lists each type."
                },
                "property": {
                  "type": "string",
                  "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID."
                },
                "operator": {
                  "type": "string",
                  "enum": [
                    "EQUALS",
                    "NOT_EQUALS",
                    "GREATER_THAN",
                    "GREATER_THAN_OR_EQUAL_TO",
                    "LESS_THAN",
                    "LESS_THAN_OR_EQUAL_TO",
                    "CONTAINS",
                    "STARTS_WITH",
                    "IS_SET",
                    "IS_NOT_SET"
                  ],
                  "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value."
                },
                "value": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    }
                  ],
                  "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET."
                }
              },
              "required": [
                "type"
              ]
            },
            "maxItems": 20,
            "description": "Filters for this measure only, on top of the query's filters."
          },
          "isBaseline": {
            "type": "boolean",
            "description": "Mark one measure as the baseline: every series also reports its value as a percentage of it."
          },
          "color": {
            "type": "string",
            "enum": [
              "GREEN",
              "RED",
              "ORANGE",
              "PURPLE",
              "GREY",
              "BLUE",
              "PEACH",
              "TEAL",
              "INDIGO",
              "AMBER",
              "ROSE",
              "CYAN"
            ],
            "description": "Chart color on a dashboard."
          }
        }
      },
      "minItems": 1,
      "maxItems": 10,
      "description": "What to aggregate: 1 to 10 measures."
    },
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "METRIC_PROPERTY",
              "CALL_PROPERTY",
              "AGENT_PROPERTY",
              "CALL_ID",
              "MODALITY",
              "DATASET",
              "METRIC_VALUE"
            ],
            "description": "What the filter narrows on. GET /v1/analytics/schema lists each type."
          },
          "property": {
            "type": "string",
            "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID."
          },
          "operator": {
            "type": "string",
            "enum": [
              "EQUALS",
              "NOT_EQUALS",
              "GREATER_THAN",
              "GREATER_THAN_OR_EQUAL_TO",
              "LESS_THAN",
              "LESS_THAN_OR_EQUAL_TO",
              "CONTAINS",
              "STARTS_WITH",
              "IS_SET",
              "IS_NOT_SET"
            ],
            "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value."
          },
          "value": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ],
            "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET."
          }
        },
        "required": [
          "type"
        ]
      },
      "maxItems": 20,
      "description": "Applied to every measure, on top of each measure's own filters."
    },
    "interval": {
      "type": "string",
      "enum": [
        "HOUR",
        "DAY",
        "WEEK",
        "MONTH"
      ],
      "description": "Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets."
    },
    "comparisonMode": {
      "type": "string",
      "enum": [
        "NONE",
        "PREVIOUS_PERIOD"
      ],
      "description": "PREVIOUS_PERIOD adds the preceding window of the same length to every series."
    },
    "comparisonGroups": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The series label; unique within the query."
          },
          "filters": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "METRIC_PROPERTY",
                    "CALL_PROPERTY",
                    "AGENT_PROPERTY",
                    "CALL_ID",
                    "MODALITY",
                    "DATASET",
                    "METRIC_VALUE"
                  ],
                  "description": "What the filter narrows on. GET /v1/analytics/schema lists each type."
                },
                "property": {
                  "type": "string",
                  "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID."
                },
                "operator": {
                  "type": "string",
                  "enum": [
                    "EQUALS",
                    "NOT_EQUALS",
                    "GREATER_THAN",
                    "GREATER_THAN_OR_EQUAL_TO",
                    "LESS_THAN",
                    "LESS_THAN_OR_EQUAL_TO",
                    "CONTAINS",
                    "STARTS_WITH",
                    "IS_SET",
                    "IS_NOT_SET"
                  ],
                  "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value."
                },
                "value": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    }
                  ],
                  "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET."
                }
              },
              "required": [
                "type"
              ]
            },
            "minItems": 1,
            "maxItems": 20
          },
          "color": {
            "type": "string",
            "enum": [
              "GREEN",
              "RED",
              "ORANGE",
              "PURPLE",
              "GREY",
              "BLUE",
              "PEACH",
              "TEAL",
              "INDIGO",
              "AMBER",
              "ROSE",
              "CYAN"
            ]
          }
        },
        "required": [
          "name",
          "filters"
        ]
      },
      "minItems": 2,
      "maxItems": 5,
      "description": "Run every measure once per named filter set, e.g. one group per agent."
    },
    "timeRange": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "LAST"
            },
            "value": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            },
            "unit": {
              "type": "string",
              "enum": [
                "DAYS",
                "WEEKS",
                "MONTHS"
              ]
            }
          },
          "required": [
            "type",
            "value",
            "unit"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "CALENDAR_ALIGNED"
            },
            "period": {
              "type": "string",
              "enum": [
                "TODAY",
                "YESTERDAY",
                "THIS_WEEK",
                "LAST_WEEK",
                "THIS_MONTH",
                "LAST_MONTH",
                "THIS_YEAR",
                "LAST_YEAR"
              ]
            }
          },
          "required": [
            "type",
            "period"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "FIXED"
            },
            "from": {
              "type": "string",
              "format": "date-time"
            },
            "to": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "type",
            "from",
            "to"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "SINCE"
            },
            "from": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "type",
            "from"
          ]
        }
      ],
      "description": "Defaults to the last 30 days."
    },
    "timezone": {
      "type": "string",
      "minLength": 1,
      "description": "IANA zone that buckets and calendar periods align to, e.g. America/New_York. Defaults to UTC."
    },
    "includeBuckets": {
      "type": "boolean",
      "description": "Set false to return only the window totals."
    }
  },
  "required": [
    "measures"
  ]
}