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

### Request

```bash
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

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

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "diagnostics": [
      {
        "code": "INVALID_QUERY",
        "path": [
          "string"
        ],
        "message": "string",
        "fix": "string",
        "suggestions": [
          "string"
        ]
      }
    ],
    "parameter": "string"
  }
}
```

---

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