Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"from",
"measures",
"website_id"
],
"properties": {
"by": {
"type": "array",
"items": {
"type": "string"
},
"description": "GROUP BY dimensions. Omit for scalar result."
},
"from": {
"enum": [
"attributes",
"citations",
"competitors",
"contents",
"prompts",
"response_mentions",
"responses",
"source_mentions",
"sources",
"topics",
"websites"
],
"type": "string",
"description": "Dataset to query. Cubes and their contracts:\nEach cube lists its selectable fields, then: filter-only (usable only in where), alsoSelect (name←id: group by the id, pass the name in alsoSelect), groupable (the only fields accepted in by), max limit (the most rows one call returns), and order by index (dims in orderBy that are not in by must follow this order, skipping allowed).\nwebsites:\n created_at, default_language, industry, normalized_url, org_id, website_id, website_name, website_url | groupable: website_id, org_id, industry, default_language | max limit 1000 (default 100) | order by index: website_id\ncompetitors:\n created_at, entity_id, entity_name, website_id | alsoSelect: entity_name←entity_id | groupable: website_id, entity_id | max limit 1000 (default 100) | order by index: website_id, entity_id\nprompts:\n created_at, is_paused, language, monthly_searches, prompt_id, prompt_text, prompt_type, topic_id, topic_name, total_value, website_id | filter-only: prompt_tag_ids | alsoSelect: topic_name←topic_id | groupable: website_id, topic_id, prompt_type, is_paused | max limit 1000 (default 100) | order by index: website_id, monthly_searches, total_value, prompt_id\nresponses:\n cited, company_count, country, date, location_id, model_category, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, prompt_variation, response_id, sentiment, sentiment_score, target_identifiers, target_rank, topic_name, website_id, content | filter-only: is_base_prompt, prompt_tag_ids, response_mentions_entity | alsoSelect: prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, prompt_id, model_category, sentiment, prompt_type, prompt_topic_id, persona_id, location_id | max limit 100 (default 100) | order by index: website_id, date, prompt_id, response_id\nresponse_mentions:\n country, date, entity_id, entity_name, identifier, is_website, location_id, mention_id, model_category, persona_id, position, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, rank, rank_percentile, response_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, ranked_count, response_mentions_entity | alsoSelect: entity_name←entity_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, is_website, prompt_id, model_category, prompt_topic_id, persona_id, location_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id\nattributes:\n attribute_id, attribute_mention_id, attribute_name, country, date, entity_id, entity_name, is_website, location_id, model_category, persona_id, positive, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, response_mentions_entity | alsoSelect: entity_name←entity_id, attribute_name←attribute_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, attribute_id, positive, is_website, prompt_topic_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id, attribute_id\nsources:\n content_id, content_title, content_type, country, date, domain, full_url, location_id, model_category, normalized_url, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, source_id, topic_name, website_id | filter-only: is_attributed_content, prompt_tag_ids, response_mentions_entity | alsoSelect: prompt_text←prompt_id, topic_name←prompt_topic_id, content_title←content_id | groupable: website_id, date, domain, normalized_url, full_url, prompt_id, model_category, prompt_topic_id, content_id, content_type | max limit 10000 (default 1000) | order by index: website_id, date, domain\ncitations:\n citation_id, country, date, domain, entity_id, entity_name, is_website, location_id, model_category, normalized_url, persona_id, prompt_id, prompt_is_deleted, prompt_language, prompt_status, prompt_text, prompt_topic_id, prompt_type, response_id, source_id, topic_name, website_id | filter-only: is_competitor, prompt_tag_ids, response_mentions_entity | alsoSelect: entity_name←entity_id, prompt_text←prompt_id, topic_name←prompt_topic_id | groupable: website_id, date, entity_id, domain, normalized_url, source_id, prompt_id, model_category, prompt_topic_id | max limit 10000 (default 1000) | order by index: website_id, date, entity_id, domain\nsource_mentions:\n date, domain, entity_id, entity_name, is_website, normalized_url, source_unique_id, website_id | filter-only: is_competitor | alsoSelect: entity_name←entity_id | groupable: website_id, date, entity_id, is_website, domain, normalized_url, source_unique_id | max limit 10000 (default 1000) | order by index: website_id, domain, date, entity_id\ntopics:\n created_at, topic_description, topic_id, topic_name, website_id | groupable: website_id, topic_id | max limit 1000 (default 100) | order by index: website_id, topic_id\ncontents:\n content_id, content_type, created_at, date, effective_date, normalized_url, sheet_id, status, title, topic_id, topic_name, updated_at, url, website_id | alsoSelect: topic_name←topic_id, title←content_id | groupable: website_id, status, topic_id, content_type | max limit 1000 (default 100) | order by index: website_id, effective_date, created_at, content_id"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Max rows to return."
},
"where": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
],
"description": "WHERE filter (before grouping)."
},
"having": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
],
"description": "HAVING filter (after grouping). References measure aliases and by dims."
},
"compare": {
"type": "object",
"required": [
"baseline",
"current"
],
"properties": {
"current": {
"$ref": "#/definitions/CompareSlice"
},
"baseline": {
"$ref": "#/definitions/CompareSlice"
}
},
"description": "Compare the same measures across two slices. Each base measure `m` expands to `m_<baseline.label>` and `m_<current.label>`; the result also gets `m_delta` (= current − baseline) and `m_pct_change` (= (current − baseline) / baseline, null when baseline = 0). Default labels are 'baseline' and 'current'; override per side for non-temporal compares (e.g. brand vs competitors). One scan; orderBy on `m_delta` works push-down."
},
"orderBy": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"description": "Dim or measure name, ascending."
},
{
"type": "object",
"required": [
"dim"
],
"properties": {
"dim": {
"type": "string"
},
"desc": {
"type": "boolean"
}
}
},
{
"type": "object",
"required": [
"measure"
],
"properties": {
"desc": {
"type": "boolean"
},
"measure": {
"type": "string"
}
}
}
]
},
"description": "ORDER BY. Measure aliases and by dims allowed."
},
"measures": {
"type": "object",
"description": "Aggregate expressions keyed by output column name. Example: { total: { fn: 'count_distinct', of: 'response_id' } }",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "object",
"required": [
"fn"
],
"properties": {
"fn": {
"enum": [
"count",
"count_distinct",
"avg",
"sum",
"min",
"max"
],
"type": "string",
"description": "Aggregate function."
},
"of": {
"type": "string",
"description": "Dimension to aggregate. Required for all functions except count. Bare `count` (no `of`) counts distinct facts (responses, mentions, citations...) on fact cubes. It throws on pre-aggregated tables (MVs) where rows are groups, not facts — use `{ fn: 'count_distinct', of: '<id-dim>' }` instead (e.g. `of: 'response_id'` on mentions/citations) to hit the MV's pre-computed aggregate."
},
"where": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
],
"description": "Per-measure conditional filter (compiles to countIf, avgIf, etc.)."
}
},
"description": "Aggregate expression."
},
{
"type": "object",
"required": [
"expr"
],
"properties": {
"expr": {
"$ref": "#/definitions/Expr"
}
},
"description": "Derived measure — an s-expression computed over other measures. Refs resolve to other measure aliases in the same query. Example: { expr: [\"/\", \"brand\", [\"nullIf\", \"total\", 0]] }"
}
]
}
},
"schedule": {
"anyOf": [
{
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
{
"type": "array",
"items": {
"anyOf": [
{
"enum": [
"default",
"manual"
],
"type": "string"
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
"maxItems": 50,
"minItems": 1
}
],
"description": "One schedule from the catalog (\"default\" or a custom/archived UUID), or an array of them to combine their data. Omit to use the caller default. The retired \"manual\" token is accepted as a deprecated alias of \"default\". Website-level cubes are unaffected."
},
"alsoSelect": {
"type": "array",
"items": {
"type": "string"
},
"description": "Label dimensions carried via any(). Must be determined by a by dim (cube's dependentDims). Example: entity_name when entity_id is in by."
},
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The website to query. Must be a website your credentials can access."
}
},
"definitions": {
"Expr": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/definitions/Expr"
},
"minItems": 1
}
],
"description": "S-expression. Strings are refs (to a measure alias or by-dim). Numbers/booleans/null are literals. Arrays are [op, ...args] where op is a binary operator (+ - * / % = != < <= > >= AND OR) or one of the allowed scalar functions: nullIf, coalesce, ifNull, if, multiIf, abs, round, floor, ceil, sqrt, pow, least, greatest, log, exp, sign. Examples: [\"-\", \"n_current\", \"n_baseline\"], [\"/\", \"num\", [\"nullIf\", \"denom\", 0]], [\"coalesce\", \"value\", 0]."
},
"Filter": {
"type": "object",
"properties": {
"OR": {
"type": "array",
"items": {
"$ref": "#/definitions/Filter"
},
"minItems": 1
},
"AND": {
"anyOf": [
{
"$ref": "#/definitions/Filter"
},
{
"type": "array",
"items": {
"$ref": "#/definitions/Filter"
},
"minItems": 1
}
]
},
"NOT": {
"allOf": [
{
"$ref": "#/definitions/Filter"
}
]
}
},
"description": "Prisma-style filter. A bare scalar value on a dim is shorthand for `eq` (e.g. `{ is_website: true }`); bare arrays and op-less objects throw — use `{ in: [...] }` / `{ hasSome: [...] }` explicitly. Operators: eq, neq, in, notIn, gt, gte, lt, lte, isNull, like, ilike, startsWith, hasSome, hasEvery, hasNone. Combinators: AND, OR, NOT. On semi-join dims (e.g. `response_mentions_entity`, `prompt_tag_ids`), `hasSome`/`in` emit `IN (SELECT …)` and `hasNone`/`notIn` emit `NOT IN (SELECT …)`; combine both on one dim to express \"includes any of A but none of B\". Empty `AND: []` / `OR: []` throw (the math identities are asymmetric — drop the clause before passing). Empty list operators (`hasSome: []` / `hasNone: []` / `hasEvery: []`) also throw — drop the predicate or supply at least one value. NOT accepts a single Filter only — for arrays use `NOT: { AND: [...] }` (`not all`) or `NOT: { OR: [...] }` (`none`). NOT keeps rows whose value is NULL: `NOT { sentiment: { eq: \"positive\" } }` returns unanalyzed responses as well as negative and neutral ones, because \"not positive\" is true of a row with no sentiment. Exclude them explicitly with `AND: [{ NOT: {...} }, { sentiment: { isNull: false } }]`.",
"additionalProperties": {}
},
"CompareSlice": {
"type": "object",
"required": [
"where"
],
"properties": {
"label": {
"type": "string"
},
"where": {
"$ref": "#/definitions/Filter"
}
},
"description": "One side of a compare. `where` is the filter that scopes this slice (non-empty — empty means 'all rows', which trivializes the comparison). `label` defaults to 'baseline' / 'current' and forms the suffix on expanded column names; override for non-temporal compares."
}
},
"additionalProperties": false
}