# 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](https://doc.fours.com/settings/oauth-app/)._

### Request

```bash
curl -X GET 'https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}' \
  -H "Authorization: Bearer $SUGER_TOKEN"
```

### Response — 200

```json
{
  "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

```json
{
  "error": "string"
}
```

---

API reference: https://doc.fours.com/api/
