# Run an Analytics Query

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

Runs a query against the organization's published analytics data and returns its rows, with each column's name, role and type. Write the query in the grammar from GetAnalyticsQueryGrammar, with the names from GetAnalyticsDataset, and check it with DescribeAnalyticsQuery first. A query that does not pass is refused with the diagnostics; one that would read too much data is refused with COST_TOO_HIGH, so narrow its time range or add a filter. A records query returns a page at a time: send `page.next` back as its `cursor`. The answer's `notes`, where it has any, say what the query may not mean as written: act on them before answering from its rows.

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

## Responses

### 200 — The query's result, with the check's notes on the query

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

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

### 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; COST_TOO_HIGH: the query would read too much data; or INVALID_REQUEST

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/query' \
  -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"
          }
        ]
      }
    ]
  }
}'
```

### Response — 200

```json
{
  "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"
      }
    ]
  },
  "rows": [
    {}
  ],
  "meta": {
    "dataVersion": "string",
    "asOf": "string",
    "truncated": true,
    "range": {
      "from": "string",
      "to": "string"
    },
    "unbounded": true,
    "fxAsOf": "string",
    "fxMissing": [
      "string"
    ]
  },
  "page": {
    "next": "string"
  }
}
```

### Error — 401

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

---

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