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

NameInTypeRequiredDescription
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:

FieldTypeRequiredDescription
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:

FieldTypeRequiredDescription
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:

FieldTypeRequiredDescription
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:

FieldTypeRequiredDescription
error string yes Error message

403 — Not a member of the organization

Content-Type: application/json · Schema: AiErrorResponse

AiErrorResponse fields:

FieldTypeRequiredDescription
error string yes Error message

404 — NOT_FOUND

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

500 — ANALYTICS_UNAVAILABLE: an unexpected failure

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

503 — ANALYTICS_UNAVAILABLE: analytics is not configured or not ready

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
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.