Run an Analytics Query
POST https://api.suger.cloud/ai/org/{orgId}/analytics/query
Runs a query against the organization's published analytics data and returns its rows, with each column's name, role and type. Write the query in the grammar from GetAnalyticsQueryGrammar, with the names from GetAnalyticsDataset, and check it with DescribeAnalyticsQuery first. A query that does not pass is refused with the diagnostics; one that would read too much data is refused with COST_TOO_HIGH, so narrow its time range or add a filter. A records query returns a page at a time: send `page.next` back as its `cursor`. The answer's `notes`, where it has any, say what the query may not mean as written: act on them before answering from its rows.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | Organization ID |
Request Body
Required. Content-Type: application/json · Schema: object
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
query | object | yes | An analytics query, in the grammar GetAnalyticsQueryGrammar gives, naming only the datasets ListAnalyticsDatasets lists and the fields, measures and segments GetAnalyticsDataset lists. |
Responses
200 — The query's result, with the check's notes on the query
Content-Type: application/json · Schema: AnalyticsQueryAnswer
401 — No valid token
Content-Type: application/json · Schema: AiErrorResponse
AiErrorResponse fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | Error message |
403 — Not a member of the organization, or DATASET_FORBIDDEN: the query reads a dataset the caller may not read
Content-Type: application/json
413 — INVALID_REQUEST: the body is larger than 256 KiB
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
422 — QUERY_REJECTED, with diagnostics; COST_TOO_HIGH: the query would read too much data; or INVALID_REQUEST
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
429 — BUSY: too many analytics queries are running
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
500 — ANALYTICS_UNAVAILABLE: an unexpected failure
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
503 — ANALYTICS_UNAVAILABLE: analytics is not configured or not ready, or the analytics database failed the query; worth a retry
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
504 — TIMEOUT: the query ran past its time limit
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
Example
The request bodies are this operation's documented examples; the
response and error bodies are generated from its schema. Substitute your
own ids, and set SUGER_TOKEN to a bearer token from the
OAuth client-credentials exchange.
Request
curl -X POST 'https://api.suger.cloud/ai/org/{orgId}/analytics/query' \
-H "Authorization: Bearer $SUGER_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"query": {
"v": 1,
"from": {
"dataset": "revenue"
},
"stages": [
{
"kind": "aggregate",
"where": {
"op": "within",
"arg": {
"op": "field",
"path": [
"invoice_date"
]
},
"range": {
"last": 12,
"unit": "month"
}
},
"group": {
"month": {
"op": "trunc",
"arg": {
"op": "field",
"path": [
"invoice_date"
]
},
"unit": "month"
},
"currency": {
"op": "field",
"path": [
"currency"
]
}
},
"measures": {
"net_revenue": {
"op": "measure",
"name": "net_revenue"
}
},
"order": [
{
"by": "month"
}
]
}
]
}
}' Response — 200
{
"schema": {
"kind": "aggregate",
"columns": [
{
"name": "Acme Corp",
"role": "dimension",
"label": "string",
"type": {},
"nullable": true,
"approximate": true,
"additive": true,
"time": {
"grain": "day"
},
"change": {
"vs": "previous",
"of": "string",
"as": "delta"
},
"bin": {
"width": 100
}
}
],
"limit": 1,
"order": [
{
"by": "string",
"dir": "asc"
}
]
},
"rows": [
{}
],
"meta": {
"dataVersion": "string",
"asOf": "string",
"truncated": true,
"range": {
"from": "string",
"to": "string"
},
"unbounded": true,
"fxAsOf": "string",
"fxMissing": [
"string"
]
},
"page": {
"next": "string"
}
} Error — 401
{
"error": "string"
} View as Markdown · API reference overview
Spotted something wrong or out of date on this page? Tell us and we'll correct it.