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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | Organization ID |
Request Body
Required. Content-Type: application/json · Schema: object
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| 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. |
Responses
201 — The saved chart
Content-Type: application/json · Schema: AnalyticsSavedChart
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, 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:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
422 — QUERY_REJECTED, with diagnostics, or INVALID_REQUEST
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
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.