Save an Analytics Chart

POST https://api.suger.cloud/ai/org/{orgId}/analytics/chart

Saves a chart: a query, and the config that draws its result when one is given, both checked as DescribeAnalyticsQuery checks them. Without a config, the chart is drawn as the result's shape asks. A chart that does not pass is refused with the diagnostics. The new chart is at version 1. A chart config's `axis` is `{ zero, log, min, max }`, each optional, for the value axis: whether it includes zero (it does unless it is logarithmic), whether it is logarithmic, and where it starts and ends, `min` below `max` and both above zero on a log axis.

Parameters

NameInTypeRequiredDescription
orgId path string yes Organization ID

Request Body

Required. Content-Type: application/json · Schema: object

Request body fields:

FieldTypeRequiredDescription
title string yes
description string no
query object yes An analytics query, in the grammar GetAnalyticsQueryGrammar gives, naming only the datasets ListAnalyticsDatasets lists and the fields, measures and segments GetAnalyticsDataset lists.
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.

Responses

201 — The saved chart

Content-Type: application/json · Schema: AnalyticsSavedChart

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, a role that cannot write, or DATASET_FORBIDDEN: the query reads a dataset the caller may not read

Content-Type: application/json

413 — INVALID_REQUEST: the body is larger than 256 KiB

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

422 — QUERY_REJECTED, with diagnostics, or INVALID_REQUEST

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

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/chart' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Net revenue by month",
  "description": "Net revenue over the last 12 months, by currency.",
  "query": {
    "v": 1,
    "from": {
      "dataset": "revenue"
    },
    "stages": [
      {
        "kind": "aggregate",
        "where": {
          "op": "within",
          "arg": {
            "op": "field",
            "path": [
              "invoice_date"
            ]
          },
          "range": {
            "last": 12,
            "unit": "month"
          }
        },
        "group": {
          "month": {
            "op": "trunc",
            "arg": {
              "op": "field",
              "path": [
                "invoice_date"
              ]
            },
            "unit": "month"
          },
          "currency": {
            "op": "field",
            "path": [
              "currency"
            ]
          }
        },
        "measures": {
          "net_revenue": {
            "op": "measure",
            "name": "net_revenue"
          }
        },
        "order": [
          {
            "by": "month"
          }
        ]
      }
    ]
  },
  "chart": {
    "type": "line",
    "x": "month",
    "y": "net_revenue",
    "series": "currency"
  }
}'

Response — 201

{
  "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
  }
}

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.