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

NameInTypeRequiredDescription
orgId path string yes Organization ID

Request Body

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

Request body fields:

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

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

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

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

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

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