Skip to main content
POST
/
v1
/
cubesql
SQL query
curl --request POST \
  --url https://{deployment}.{region}.cubecloudapp.dev/cubejs-api/v1/cubesql \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "timezone": "<string>",
  "cache": "stale-if-slow"
}
'
{
  "schema": [
    {
      "name": "value",
      "column_type": "Int64"
    }
  ],
  "lastRefreshTime": "2025-01-13T12:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Cube API token (a JWT). Sent directly in the Authorization header, e.g. Authorization: <CUBE_API_TOKEN> (no "Bearer" prefix).

Body

application/json
​
query
string
required

The SQL query to run.

​
timezone
string

Time zone for the query in TZ database name format, e.g. America/Los_Angeles.

​
cache
enum<string>
default:stale-if-slow

In-memory cache strategy (see Cache control):

  • stale-if-slow (default): if refresh keys are up to date, return the cached value; if expired, fetch fresh data but fall back to the stale value when the source query is slow.
  • stale-while-revalidate: if expired, return stale data immediately and refresh the cache in the background.
  • must-revalidate: if expired, always wait for fresh data from the source, even if slow.
  • no-cache: skip refresh-key checks and always query the data source.
Available options:
stale-if-slow,
stale-while-revalidate,
must-revalidate,
no-cache

Response

200 - application/json

Newline-delimited JSON stream. The first line carries schema (and optionally lastRefreshTime); subsequent lines carry data chunks.

​
schema
object[]
​
lastRefreshTime
string<date-time>
​
data
any[][]