REST API
API: Query
Run read-only SQL against a source, or compile a visual step graph to SQL. All endpoints require authentication unless noted. 13 endpoints.
POST /api/query-builder/preview
Section titled “POST /api/query-builder/preview”Compile a visual step graph to SQL and preview rows (QB-2)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
steps |
array of object | yes | |
outputStepId |
string | no | |
limit |
integer | no | |
dryRun |
boolean | no |
Responses: 200
POST /api/query/batch
Section titled “POST /api/query/batch”Execute multiple ChartSpec queries in a single batch
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
specs |
array of object | yes | |
forceRefresh |
boolean | no |
Responses: 200 · 400 · 401 · 404
DELETE /api/query/cache/{modelId}
Section titled “DELETE /api/query/cache/{modelId}”Clear cached query results for a model
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
modelId |
string | yes |
Responses: 200 · 400 · 401 · 404 · 503
POST /api/query/card-data
Section titled “POST /api/query/card-data”Run the saved query backing a dashboard card (view-gated)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
dashboardId |
string | yes | |
cardId |
string | yes | |
limit |
integer | no | |
filters |
array of object | no | |
distinctColumn |
string | no |
Responses: 200 · 400 · 401 · 403 · 404
POST /api/query/distinct
Section titled “POST /api/query/distinct”Get distinct values for a field (for slicers/filters)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
modelId |
string | yes | |
sourceId |
string | yes | |
fieldId |
string | yes | |
limit |
number | no |
Responses: 200
POST /api/query/execute
Section titled “POST /api/query/execute”Execute a ChartSpec query against a semantic model
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
modelId |
string | yes | |
sourceId |
string | yes | |
xField |
object | no | |
yFields |
array of object | yes | |
colorField |
object | no | |
smallMultiples |
object | no | |
latField |
object | no | |
lonField |
object | no | |
sizeField |
object | no | |
tooltipFields |
array of object | no | |
filters |
array of object | no | |
sort |
array of object | no | |
limit |
integer | no | |
offset |
integer | no | |
forceRefresh |
boolean | no |
Responses: 200 · 400 · 401 · 404
POST /api/query/matrix
Section titled “POST /api/query/matrix”Query an authorized hierarchy branch and its semantic subtotal
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
spec |
object | yes | |
rowFields |
array of object | yes | |
columnFields |
array of object | yes | |
rowPath |
array of object | yes | |
columnPath |
array of object | yes | |
includeRows |
boolean | yes | |
includeColumns |
boolean | yes |
Responses: 200 · 400 · 401 · 404
POST /api/query/matrix/export
Section titled “POST /api/query/matrix/export”Export every bounded hierarchy level with independently calculated source totals
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
spec |
object | yes | |
rowFields |
array of object | yes | |
columnFields |
array of object | yes |
Responses: 200 · 400 · 401 · 404
POST /api/query/raw
Section titled “POST /api/query/raw”Execute raw SQL against a data source (admin/editor only)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
sourceId |
string | yes | |
sql |
string | yes | |
limit |
integer | no |
Responses: 200 · 400 · 401 · 403 · 404 · 429
POST /api/query/report-block-data
Section titled “POST /api/query/report-block-data”Run the saved query backing a report block (view-gated), with the report’s filters on the block
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
reportId |
string | yes | |
savedQueryId |
string | yes | |
blockId |
string | no | |
filters |
array of object | no | |
limit |
integer | no |
Responses: 200 · 400 · 401 · 403 · 404
POST /api/query/story-block-data
Section titled “POST /api/query/story-block-data”Run the saved query behind a story’s live data block (read-gated by the story); a frozen story’s kept rows
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
storyId |
string | yes | |
savedQueryId |
string | yes | |
revision |
"working" | "published" |
no | |
parameters |
object | no | |
dataMode |
"auto" | "live" | "captured" |
no | captured requires a frozen story’s published version with its authored defaults and available kept rows; it never runs a live fallback query. |
contentRevision |
integer | no | |
limit |
integer | no |
Responses: 200 · 400 · 401 · 404
POST /api/query/table
Section titled “POST /api/query/table”Explore all filtered query rows through immutable, user-scoped table pages
The chart’s Top N and offset do not apply. Existing query memory safeguards remain: totalRows is null and complete is false when capped. Snapshots expire after five minutes; every page rechecks model, source, masking and RLS context. Shared links use their existing bounded endpoints.
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
spec |
object | yes | |
pageSize |
integer | no | |
cursor |
string | no | |
sort |
array of object | no |
Responses: 200 · 400 · 401 · 404
POST /api/query/table/totals
Section titled “POST /api/query/table/totals”Evaluate authored aggregate measures over the whole filter context
Recalculates measures at total grain instead of summing groups. Runs as an independent source query; unavailable totals include an explanation.
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
spec |
object | yes |
Responses: 200 · 400 · 401 · 404