Get the rows behind a chart block
POST https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}/blocks/{blockId}/detail
Lists a page of the records behind a chart block's numbers: its dataset's detail fields, newest first, under the chart's own conditions, the viewer's `state`, and the `mark` clicked, a value for each dimension it names. They are the records of the groups the chart draws under that state, every one for a whole tile: a mark the chart does not draw, such as a group a `having` or a `limit` leaves out, is refused with 422, a chart with a later stage shows none, and one whose query fails its check under that state shows none, refused as its own read is. Of those, they are the rows the `measure` the mark is of reads, under its own condition, or with no measure named the rows any of the chart's measures reads. The rows can name buyers and amounts, so they are read with the caller's permissions, and only when the dashboard's `interactions.detail` is on. `cursor` reads the page after the one whose `result.page.next` it is: an empty one is none, the first page, and any other is refused with 400. The `state` is `{ filters, cross, drill }`: `filters` gives each filter's value by its id; `cross` lists the clicks on charts' marks, each `{ block, output, values }` (the values of the chart block's output clicked) or `{ block, output, other }` (a click on Other: every value of the output but those listed, the ones the chart shows on their own); `drill` lists the drills, each `{ block, output, value, by }`: the chart block filtered to one value of its output and broken down by the field `by` in its place. `version` names the version of the dashboard the page drew: one saved at another version since is refused with VERSION_CONFLICT before anything is read, its block or state included. Without it, the latest version is read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | Organization ID |
dashboardId | path | string | yes | |
blockId | path | string | yes |
Request Body
Required. Content-Type: application/json · Schema: object
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
version | integer | no | The version of the dashboard the page reading it drew, as GetAnalyticsDashboard answered it: a dashboard saved at another version since is refused with VERSION_CONFLICT, naming the version it is at, and nothing is read. Without one, the latest version is read. |
state | AnalyticsDashboardState | no | |
mark | object | no | |
measure | string | no | The measure the clicked mark is of: the rows are those it reads, under its own condition. Only with a `mark`; without one, the rows are those any of the chart's measures reads. |
cursor | string | no |
AnalyticsDashboardState fields:
| Field | Type | Required | Description |
|---|---|---|---|
filters | object | yes | |
cross | array<object> | yes | |
drill | array<object> | yes |
Responses
200 — A page of records
Content-Type: application/json · Schema: AnalyticsDashboardDetail
AnalyticsDashboardDetail fields:
| Field | Type | Required | Description |
|---|---|---|---|
result | AnalyticsQueryResult | yes |
AnalyticsQueryResult fields:
| Field | Type | Required | Description |
|---|---|---|---|
schema | object | yes | |
rows | array<object> | yes | One object per row, keyed by the result's column names. |
page | object | no | A records page: `next` is the cursor of the following page, absent on the last one. |
meta | object | yes |
400 — INVALID_REQUEST: a cursor that is not one of the block's pages
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
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
404 — NOT_FOUND: no dashboard, no chart block with this id, or detail is off
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
409 — VERSION_CONFLICT: the read names a version the dashboard was saved past; nothing is read
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
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 — INVALID_REQUEST: the mark names no dimension of the chart or a group it does not draw, the measure none of its measures, the chart has a later stage, or a value of the state cannot be read; QUERY_REJECTED, with diagnostics
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/dashboard/{dashboardId}/blocks/{blockId}/detail' \
-H "Authorization: Bearer $SUGER_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"mark": {
"partner": "AWS"
}
}' Response — 200
{
"result": {
"schema": {
"kind": "aggregate",
"columns": [
{
"name": "Acme Corp",
"role": "dimension",
"label": "string",
"type": {},
"nullable": true,
"approximate": true,
"additive": true,
"time": {},
"change": {},
"bin": {}
}
],
"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 — 400
{
"error": {
"code": "string",
"message": "string",
"diagnostics": [
{
"code": "INVALID_QUERY",
"path": [
"string"
],
"message": "string",
"fix": "string",
"suggestions": [
"string"
]
}
],
"parameter": "string"
}
} View as Markdown · API reference overview
Spotted something wrong or out of date on this page? Tell us and we'll correct it.