Get a Saved Analytics Dashboard
GET https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}
Gets a dashboard's document with the live saved charts the caller may read, in reading order, and for each filter the chart blocks it reaches, for each chart what a click on it filters by and the chart blocks that click reaches, and the fields each chart can be broken down by. A chart's query, and a chart block's own query and config, are included only when the caller can read every dataset the query reads.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | Organization ID |
dashboardId | path | string | yes |
Responses
200 — The dashboard, its charts, and what its filters reach
Content-Type: application/json · Schema: AnalyticsDashboardRead
AnalyticsDashboardRead fields:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
title | string | yes | |
description | string | no | |
version | integer | yes | |
createdBy | string or null | yes | |
createdAt | string | yes | |
updatedAt | string | yes | |
builtin | string | no | The built-in dashboard Analytics setup added this one as, such as `suger-finance-view`; absent on every other. Only setup sets it: a create or an update naming it is refused, and an update keeps it. |
filters | array<AnalyticsDashboardReadFilter> | yes | |
blocks | array<AnalyticsDashboardReadBlock> | yes | |
interactions | object | no | `crossFilter`: a click on a mark filters the other charts. `detail`: a mark's rows can be shown, and its chart broken down by another field. Both on when absent. |
charts | array<AnalyticsSavedChart> | yes | |
reach | object | yes | Each filter's id, with the chart blocks it reaches; a `range` on money whose currency is a field lists each chart a `select` over that field reaches, which it filters only once one currency is picked. |
crossFilterable | object | yes | Each chart block's id, with the outputs a click on its marks can filter by. |
crossReach | object | yes | Each chart block's id, then each output it can filter by, with the other chart blocks a click on that output filters. |
ownRange | object | no | Each filter's id, with the chart blocks it leaves keeping their own range, or their own grain: those a block's read reports it `not_reachable` on with `reason: "own_range"`, which `reach` leaves out. Always sent; an older service sent none. |
crossOwnRange | object | no | Each chart block's id, then each output it can filter by, with the other chart blocks a click on that output leaves keeping their own range: those a block's read reports it `not_reachable` on with `reason: "own_range"`, which `crossReach` leaves out. Always sent; an older service sent none. |
breakdowns | object | yes | Each chart block that can drill, with the fields of its own dataset "Break down by" offers and their labels: categories, never an id, a number, money or a date. None when the dashboard turns detail off; a drill by any other field is refused. |
defaultTimes | object | no | Each dataset the charts the caller may read are over, with its default time: the field a `time` filter adds its range on there, on a chart whose first stage keeps no `within` on a field; on any other it replaces each such `within`, on whatever date. Always sent; an older service sent none. |
filterTypes | object | no | Each select filter the caller may read, with its field's type, which names its values as a chart names them: a code as words. Always sent; an older service sent none. |
AnalyticsSavedChart fields:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
title | string | yes | |
description | string | yes | |
version | integer | yes | |
createdBy | string or null | yes | |
createdAt | string | yes | |
updatedAt | string | yes | |
query | object | no | The chart's query; absent when the caller cannot read every dataset it reads. |
chart | AnalyticsChartConfig | no |
AnalyticsChartConfig fields:
| Field | Type | Required | Description |
|---|---|---|---|
type | string | no | The chart type; without it, the type the result's shape asks for. |
x | string | no | |
y | object | no | The measure, or measures sharing one unit, to plot. |
series | string | no | A dimension output; each of its values is drawn as its own series. |
size | string | no | |
value | string | no | |
path | array<string> | no | |
rows | array<string> | no | |
across | array<string> | no | |
columns | array<string> | no | |
labels | object | no | Display names for outputs, by output name, each at most 200 characters; the model's labels otherwise. |
values | boolean | no | |
top | number | no | Keep the N largest series, slices or points; at most seven, or ten slices of a pie, whose eighth to tenth are steps of the gray, each named on its slice. |
sort | string | no | |
highlight | object | no | One series value, drawn in color while the rest are muted. |
target | number | no | A goal, in the measure's unit. |
axis | object | no | |
stack | object | no | Stack the parts end to end, or not; `percent` stacks a bar's parts as shares of its own total, its axis reading 0% to 100%. |
smooth | boolean | no | |
step | boolean | no | |
horizontal | boolean | no | |
lines | array<string> | no | |
totals | boolean | no | |
scale | string | no | |
range | array<—> | no | |
trend | boolean | no | |
period | string | no | The period a number over a time breakdown shows: `whole`, the newest whole period (the default), or `newest`, the newest period, marked partial while it is. |
donut | boolean | no | |
show | string | no | |
bars | array<string> | no | |
search | boolean | no | A table's search box, which keeps the rows a cell of which shows the text typed in it, in any case, and counts them. |
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
Content-Type: application/json · Schema: AiErrorResponse
AiErrorResponse fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | Error message |
404 — NOT_FOUND
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
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
Example
Generated from this operation's schema. Values are placeholders —
substitute your own ids, and set SUGER_TOKEN to a bearer token
from the OAuth client-credentials exchange.
Request
curl -X GET 'https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}' \
-H "Authorization: Bearer $SUGER_TOKEN" Response — 200
{
"id": "01H0000000000000000000",
"title": "string",
"version": 1,
"createdBy": "string",
"createdAt": "2026-01-31T12:00:00Z",
"updatedAt": "2026-01-31T12:00:00Z",
"filters": [
{}
],
"blocks": [
{}
],
"charts": [
{
"id": "01H0000000000000000000",
"title": "string",
"description": "string",
"version": 1,
"createdBy": "string",
"createdAt": "2026-01-31T12:00:00Z",
"updatedAt": "2026-01-31T12:00:00Z",
"query": {},
"chart": {
"type": "line",
"x": "string",
"y": "string",
"series": "string",
"size": "string",
"value": "string",
"path": [
"string"
],
"rows": [
"string"
],
"across": [
"string"
],
"columns": [
"string"
],
"labels": {},
"values": true
}
}
],
"reach": {},
"crossFilterable": {},
"crossReach": {}
} 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.