Available cubes, each as the CubeMeta discovery projection — the cube name, its title and description, and the measures/dimensions a client may name in a query. A bare array: there is no cubes wrapper object, and no cube sql is published.
Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode
string
optional
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category
string
optional
Error category (e.g. validation, authorization)
httpStatus
integer
optional
HTTP status of the response carrying this error
details
any
optional
Additional error context (e.g. field validation errors)
Target cube name — the cube to query, as GET /analytics/meta lists them, or a registered object name (read as an auto-inferred cube). Required and non-empty: an empty string names no cube and is refused at the schema.
measures
string[]
✅
List of metrics to calculate
dimensions
string[]
optional
List of dimensions to group by
where
any
optional
Filtering criteria (canonical Query DSL FilterCondition). An authored FilterArray is lowered by parseFilterAST on the client before the wire; this field admits only the lowered FilterCondition (see FilterArray in data/filter.zod.ts).
Time-bucketed dimensions. Each entry names a dimension, an optional bucket granularity, and an optional dateRange — a preset name from the closed date-range vocabulary (e.g. 'last_7_days') or an explicit [start, end] window; an unrecognised string answers 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED instead of silently widening.
order
Record<string, Enum<'asc' | 'desc'>>
optional
limit
integer
optional
Maximum number of rows to return, applied after order — a non-negative integer (0 returns no rows)
offset
integer
optional
Number of rows to skip before the first row returned, applied after order — a non-negative integer; an offset with no limit returns every row after it
Time window for this dimension: a date-range PRESET name from the closed vocabulary in data/date-range-presets.ts (today, yesterday, this_week, last_week, this_month, last_month, next_month, this_quarter, last_quarter, next_quarter, this_year, last_year, last_7_days, last_30_days, last_90_days, next_30_days — e.g. 'last_7_days'), or an explicit [start, end] array of ISO dates / {date-macro} tokens (e.g. ["2023-01-01", "2023-01-31"]). Any other string is refused at the schema with 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED.
Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode
string
optional
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category
string
optional
Error category (e.g. validation, authorization)
httpStatus
integer
optional
HTTP status of the response carrying this error
details
any
optional
Additional error context (e.g. field validation errors)
Marginal aggregates - one entry per requested totals grouping, in request order, each computed with the measure's true aggregate over the underlying data (never re-derived from bucketed values). The grand-total grouping yields a single dimensionless row.
object
string
optional
The base object of the dataset the answer was computed from: the dataset's object, by machine name. Every dataset answer (POST /analytics/dataset/query) must carry it, whatever dimensions are selected and whether or not rows came back, so a consumer can refresh on that object's record changes and drill into its records. Absent on a cube query answer, which has no dataset behind it.
dimensionFields
Record<string, string>
optional
Drill-through sidecar: each equality-drillable dimension the answer is grouped by, dimension name to that dataset dimension's own field (a base-object field or a relationship.field path). Set only on a dataset answer (POST /analytics/dataset/query) that has rows and groups by at least one dimension with a field that is not type: 'date'; a date dimension is never listed (see drillRanges). Absent on a cube query answer.
drillRawRows
Record<string, any>[]
optional
Drill-through sidecar, aligned to rows by index: each dimensionFields dimension name to the stored value that row was grouped by (a select option's value, a lookup's record id), captured before label resolution rewrites the row to its display label. An exact-match drill filter is built from these, not from the labels in rows. Set exactly when dimensionFields is.
drillRawTotals
Record<string, any>[][]
optional
Drill-through sidecar for totals: entry [i][j] aligns to totals[i].rows[j] and holds the stored value of the dimensionFields dimensions that grouping groups by, so the grand-total grouping yields an empty map per row. Set only when dimensionFields is and the answer carries at least one totals grouping.
Drill-through sidecar for date ranges, aligned to rows by index: date dimension name to the half-open range [gte, lt) that row's records fall in on that dimension's field. A time bucket gets the span it covers; a timeDimensions[].dateRange window gets the window the query filtered by on every row, or narrows the bucket entry on the same field to the part inside the window. Bounds are YYYY-MM-DD calendar days, or ISO-8601 instants when the source field is datetime (a bucket's at midnight in the reference timezone); a row whose bucket value is null gets no bucket entry, and a window whose end is an instant or the last supported day gets none. Set only on a dataset answer that has rows and groups by at least one type: 'date' dimension with a field and a granularity, or carries a dateRange on a dimension with a field; independent of dimensionFields. Absent on a cube query answer.
drillScopes
Record<string, any>
optional
Drill-through sidecar per measure: each selected measure name to the list filter, on the answer's object, that selects the records that measure aggregates: the dataset's own filter, AND the measure's own filter, AND, for a measure over a field, that field holding a value ({ "$null": false }; both instants for a duration measure), with each {token} resolved as the query resolved it; {} when none of these applies. A drill lists the clicked bucket (dimensionFields / drillRawRows / drillRawTotals, drillRanges) AND the widget's own filter AND this scope. A measure is left out when no list filter on object selects its records (a derived measure; a scope that names a relationship path such as account.region, as a key or as a $field reference), and a measure left out offers no drill. Keyed by measure name: a __compare column has no entry. Set on every dataset answer (POST /analytics/dataset/query) that has rows; absent on a cube query answer and on a draft-preview answer.
Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode
string
optional
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category
string
optional
Error category (e.g. validation, authorization)
httpStatus
integer
optional
HTTP status of the response carrying this error
details
any
optional
Additional error context (e.g. field validation errors)
Marginal aggregates - one entry per requested totals grouping, in request order, each computed with the measure's true aggregate over the underlying data (never re-derived from bucketed values). The grand-total grouping yields a single dimensionless row.
object
string
optional
The base object of the dataset the answer was computed from: the dataset's object, by machine name. Every dataset answer (POST /analytics/dataset/query) must carry it, whatever dimensions are selected and whether or not rows came back, so a consumer can refresh on that object's record changes and drill into its records. Absent on a cube query answer, which has no dataset behind it.
dimensionFields
Record<string, string>
optional
Drill-through sidecar: each equality-drillable dimension the answer is grouped by, dimension name to that dataset dimension's own field (a base-object field or a relationship.field path). Set only on a dataset answer (POST /analytics/dataset/query) that has rows and groups by at least one dimension with a field that is not type: 'date'; a date dimension is never listed (see drillRanges). Absent on a cube query answer.
drillRawRows
Record<string, any>[]
optional
Drill-through sidecar, aligned to rows by index: each dimensionFields dimension name to the stored value that row was grouped by (a select option's value, a lookup's record id), captured before label resolution rewrites the row to its display label. An exact-match drill filter is built from these, not from the labels in rows. Set exactly when dimensionFields is.
drillRawTotals
Record<string, any>[][]
optional
Drill-through sidecar for totals: entry [i][j] aligns to totals[i].rows[j] and holds the stored value of the dimensionFields dimensions that grouping groups by, so the grand-total grouping yields an empty map per row. Set only when dimensionFields is and the answer carries at least one totals grouping.
Drill-through sidecar for date ranges, aligned to rows by index: date dimension name to the half-open range [gte, lt) that row's records fall in on that dimension's field. A time bucket gets the span it covers; a timeDimensions[].dateRange window gets the window the query filtered by on every row, or narrows the bucket entry on the same field to the part inside the window. Bounds are YYYY-MM-DD calendar days, or ISO-8601 instants when the source field is datetime (a bucket's at midnight in the reference timezone); a row whose bucket value is null gets no bucket entry, and a window whose end is an instant or the last supported day gets none. Set only on a dataset answer that has rows and groups by at least one type: 'date' dimension with a field and a granularity, or carries a dateRange on a dimension with a field; independent of dimensionFields. Absent on a cube query answer.
drillScopes
Record<string, any>
optional
Drill-through sidecar per measure: each selected measure name to the list filter, on the answer's object, that selects the records that measure aggregates: the dataset's own filter, AND the measure's own filter, AND, for a measure over a field, that field holding a value ({ "$null": false }; both instants for a duration measure), with each {token} resolved as the query resolved it; {} when none of these applies. A drill lists the clicked bucket (dimensionFields / drillRawRows / drillRawTotals, drillRanges) AND the widget's own filter AND this scope. A measure is left out when no list filter on object selects its records (a derived measure; a scope that names a relationship path such as account.region, as a key or as a $field reference), and a measure left out offers no drill. Keyed by measure name: a __compare column has no entry. Set on every dataset answer (POST /analytics/dataset/query) that has rows; absent on a cube query answer and on a draft-preview answer.
That door's refusal of this query, mapped into the house error envelope: a vocabulary code (a code outside the vocabulary moves to declaredCode), a message, and details where the refusal has them.
Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode
string
optional
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category
string
optional
Error category (e.g. validation, authorization)
httpStatus
integer
optional
HTTP status of the response carrying this error
details
any
optional
Additional error context (e.g. field validation errors)
The dataset queries, in order; results[i] of the answer answers queries[i]. At least one and at most 50; an empty or over-long list refuses the whole batch (400 VALIDATION_FAILED).
Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode
string
optional
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category
string
optional
Error category (e.g. validation, authorization)
httpStatus
integer
optional
HTTP status of the response carrying this error
details
any
optional
Additional error context (e.g. field validation errors)
Time-bucketed dimensions. Each entry names a dimension, an optional bucket granularity, and an optional dateRange — a preset name from the closed date-range vocabulary (e.g. 'last_7_days') or an explicit [start, end] window; an unrecognised string answers 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED instead of silently widening.
Presentation-scope date bucketing applied to every selected date dimension; an explicit timeDimensions entry wins over it, and the dataset dimension's own default is used when neither is set
order
Record<string, Enum<'asc' | 'desc'>>
optional
limit
integer
optional
Maximum number of rows to return, applied after order — a non-negative integer (0 returns no rows)
offset
integer
optional
Number of rows to skip before the first row returned, applied after order — a non-negative integer; an offset with no limit returns every row after it
Time window for this dimension: a date-range PRESET name from the closed vocabulary in data/date-range-presets.ts (today, yesterday, this_week, last_week, this_month, last_month, next_month, this_quarter, last_quarter, next_quarter, this_year, last_year, last_7_days, last_30_days, last_90_days, next_30_days — e.g. 'last_7_days'), or an explicit [start, end] array of ISO dates / {date-macro} tokens (e.g. ["2023-01-01", "2023-01-31"]). Any other string is refused at the schema with 400 ANALYTICS_DATE_RANGE_UNRECOGNIZED.