# Check an analytics query without running it

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

Checks a query, and a chart config against the query's result when one is given, without reading any data. When the query is valid, returns the result's columns and their types, the chart drawn without a config, and the chart types the result fits; and every problem found otherwise, each with a JSON path, a message and often a fix. Write the query in the grammar from GetAnalyticsQueryGrammar, with the names from GetAnalyticsDataset. 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 |
| --- | --- | --- | --- |
| `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

### 200 — Whether the query and chart pass, and why not

Content-Type: `application/json` · Schema: `AnalyticsDescribeResult`

**`AnalyticsDescribeResult`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | boolean | yes |  |
| `schema` | object | no | The result's kind, limit and columns, when the query is valid. |
| `diagnostics` | array<AnalyticsDiagnostic> | no |  |
| `lane` | string | no | The lane the query would run in, when known. |
| `charts` | object | no | The charts the result can be drawn as, when the query is valid. |
| `notes` | array<string> | no | What a valid query may not mean as written, such as an average of period-change ratios; a note refuses nothing. |

**`AnalyticsDiagnostic`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes |  |
| `path` | array<object> | yes | Where the problem is: a JSON path into the query, or into the chart config. |
| `message` | string | yes |  |
| `fix` | string | no |  |
| `suggestions` | array<string> | no | The nearest names that exist, for a name that does not. |

### 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 |

### 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 body is not valid

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

### Request

```bash
curl -X POST 'https://api.suger.cloud/ai/org/{orgId}/analytics/describe' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "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 — 200

```json
{
  "ok": true,
  "schema": {
    "kind": "aggregate",
    "columns": [
      {
        "name": "Acme Corp",
        "role": "dimension",
        "label": "string",
        "type": {},
        "nullable": true,
        "approximate": true,
        "additive": true,
        "time": {
          "grain": "day"
        },
        "change": {
          "vs": "previous",
          "of": "string",
          "as": "delta"
        },
        "bin": {
          "width": 100
        }
      }
    ],
    "limit": 1,
    "order": [
      {
        "by": "string",
        "dir": "asc"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "INVALID_QUERY",
      "path": [
        "string"
      ],
      "message": "string",
      "fix": "string",
      "suggestions": [
        "string"
      ]
    }
  ],
  "lane": "interactive",
  "charts": {
    "inferred": {},
    "fits": [
      "line"
    ]
  },
  "notes": [
    "string"
  ]
}
```

### Error — 401

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

---

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