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

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

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

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

FieldTypeRequiredDescription
result AnalyticsQueryResult yes

AnalyticsQueryResult fields:

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

FieldTypeRequiredDescription
error object yes

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

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

FieldTypeRequiredDescription
error object yes

413 — INVALID_REQUEST: the body is larger than 256 KiB

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

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

FieldTypeRequiredDescription
error object yes

429 — BUSY: too many analytics queries are running

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, or the analytics database failed the query; worth a retry

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

504 — TIMEOUT: the query ran past its time limit

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

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