Roark · Schema

AnalyticsQuery

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.

CompanyVoice AITestingEvaluationBenchmarking

Properties

Name Type Description
measures array What to aggregate: 1 to 10 measures.
filters array Applied to every measure, on top of each measure's own filters.
interval string Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets.
comparisonMode string PREVIOUS_PERIOD adds the preceding window of the same length to every series.
comparisonGroups array Run every measure once per named filter set, e.g. one group per agent.
timeRange object Defaults to the last 30 days.
timezone string IANA zone that buckets and calendar periods align to, e.g. America/New_York. Defaults to UTC.
includeBuckets boolean Set false to return only the window totals.
View JSON Schema on GitHub

JSON Schema

roark-analytics-query-schema.json Raw ↑
{
  "$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"
  ]
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/roark-analytics-query"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.