Skip to main content

​
REST API reference

The REST API provides the following endpoints.
The {base_path} part of the endpoint URLs can be configured. By default, it’s /cubejs-api.

​
{base_path}/v1/load

Run the query to the REST API and get the results.
ParameterDescriptionRequired
queryEither a single URL encoded Cube Query, or an array of queries✅ Yes
queryTypeIf multiple queries are passed in query for data blending, this must be set to multi❌ No
cacheSee cache control. stale-if-slow by default❌ No
Response
  • query - The query passed via params. It can be an array of queries and in such case it will be treated as a Data Blending query.
  • data - Formatted dataset of query results.
  • annotation - Metadata for query. Contains descriptions for all query items.
    • title - Human readable title from the data model.
    • shortTitle - Short title for visualization usage (ex. chart overlay)
    • type - Data type
  • lastRefreshTime - An ISO 8601 timestamp indicating when the data was last refreshed.
  • total - The total number of rows returned for the query. Useful for paginating results.
Example request: 
# Request with http method GET
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query={"measures":["users.count"]}' \
  http://localhost:4000/cubejs-api/v1/load

# Request with http method POST
# Use POST to fix problem with query length limits
curl \
 -X POST  \
 -H "Content-Type: application/json" \
 -H "Authorization: TOKEN" \
 --data '{"query": {"measures":["users.count"]}}' \
 http://localhost:4000/cubejs-api/v1/load
Example response: 
{
  "query": {
    "measures": ["users.count"],
    "filters": [],
    "timezone": "UTC",
    "dimensions": [],
    "timeDimensions": []
  },
  "data": [
    {
      "users.count": "700"
    }
  ],
  "lastRefreshTime": "2025-01-13T12:00:00.000Z",
  "annotation": {
    "measures": {
      "users.count": {
        "title": "Users Count",
        "shortTitle": "Count",
        "type": "number"
      }
    },
    "dimensions": {},
    "segments": {},
    "timeDimensions": {}
  }
}
Currently all fetched numericals are returned in the same format as driver returns it without any additional processing. Most of drivers return numerical values as strings instead of javascript integer or float to ensure there’s no loss of significance. Client code should take care of parsing such numerical values.

​
{base_path}/v1/sql

Takes an API query and returns the SQL query that can be executed against the data source that is generated by Cube. This endpoint is useful for debugging, understanding how Cube translates API queries into SQL queries, and providing transparency to SQL-savvy end users. Using this endpoint to take the SQL query and execute it against the data source directly is not recommended as it bypasses Cube’s caching layer and other optimizations. Request parameters:
Parameter, typeDescriptionRequired
format, stringQuery format:
sql for SQL API queries,
rest for REST API queries (default)		❌ No
query, stringQuery as an URL-encoded JSON object or SQL query✅ Yes
disable_post_processing, booleanFlag that affects query planning, true or false❌ No
If disable_post_processing is set to true, Cube will try to generate the SQL as if the query is run without post-processing, i.e., if it’s run as a query with pushdown. The response will contain a JSON object with the following properties under the sql key:
Property, typeDescription
status, stringQuery planning status, ok or error
sql, arrayTwo-element array (see below)
sql[0], stringGenerated query with parameter placeholders
sql[1], array or objectGenerated query parameters
For queries with the sql format, the response will also include the following additional properties under the sql key:
Property, typeDescription
query_type, stringregular for regular queries,
post_processing for queries with post-processing,
pushdown for queries with pushdown
For queries with the sql format, in case of an error, the response will only contain status, query_type, and error properties. For example, an error will be returned if disable_post_processing was set to true but the query can’t be run without post-processing.

​
Example

Request with a query in the REST API format: 
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query={"measures":["orders.count"]}' \
  --data-urlencode 'format=rest'  \
  http://localhost:4000/cubejs-api/v1/sql
Response: 
{
  "sql": {
    "sql": [
      "SELECT sum(`base_orders__count`) `orders__count` FROM prod_pre_aggregations.base_orders_orders_by_month AS `base_orders__orders_by_month`  LIMIT 10000",
      []
    ]
  }
}
Request with a query in the SQL API format: 
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query=SELECT COUNT(*) FROM orders' \
  --data-urlencode 'format=sql'  \  
  http://localhost:4000/cubejs-api/v1/sql
Response: 
{
  "sql": {
    "status": "ok",
    "sql": [
      "SELECT\n      count(\"base_orders\".id) \"count_uint8_1__\"\n    FROM\n      (SELECT * FROM 's3://cube-tutorial/orders.csv') AS \"base_orders\"  LIMIT 50000",
      []
    ],
    "query_type": "regular"
  }
}
Request with a query in the SQL API format that is executed with post-processing: 
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query=SELECT AVG(count) FROM (SELECT COUNT(*) AS count FROM orders) AS table' \
  --data-urlencode 'format=sql'  \ 
  http://localhost:4000/cubejs-api/v1/sql
Response: 
{
  "sql": {
    "status": "error",
    "error": "Provided query can not be executed without post-processing.",
    "query_type": "post_processing"
  }
}
Request with a query in the SQL API format that is forced to be executed without post-processing, i.e., as a query with pushdown: 
curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query=SELECT AVG(count) FROM (SELECT COUNT(*) AS count FROM orders) AS table' \
  --data-urlencode 'format=sql' \
  --data-urlencode 'disable_post_processing=true'  \
  http://localhost:4000/cubejs-api/v1/sql
Response: 
{
  "sql": {
    "status": "ok",
    "sql": [
      "SELECT \"table\".\"avg_table_count_\" \"avg_table_count_\" \nFROM (\n  SELECT AVG(\"table\".\"count\") \"avg_table_count_\" \n  FROM (\n    SELECT\n          count(\"base_orders\".id) \"count\"\n        FROM\n          (SELECT * FROM 's3://cube-tutorial/orders.csv') AS \"base_orders\" \n  ) AS \"table\"\n) AS \"table\"\nLIMIT 50000",
      []
    ],
    "query_type": "pushdown"
  }
}

​
{base_path}/v1/meta

In Cube Cloud, consider using the Metadata API instead. It provides additional information such as data lineage.
Get meta-information for cubes and views defined in the data model. Information about cubes and views with public: false will not be returned. Response
  • cubes - Array of cubes and views
    • name - Codename of the cube/view
    • type - Type can be “cube” or “view”
    • title - Human-readable cube/view name
    • meta - Custom metadata
    • measures - Array of measures in this cube/view
    • dimensions - Array of dimensions in this cube/view
    • hierarchies - Array of hierarchies in this cube
    • segments - Array of segments in this cube/view
    • folders and nestedFolders - Arrays of flat and nested folder structures in this view, respectively
    • connectedComponent - An integer representing a join relationship. If the same value is returned for two cubes, then there is at least one join path between them.
Example request: 
curl \
  -H "Authorization: TOKEN" \
  -G \
  http://localhost:4000/cubejs-api/v1/meta
Example response: 
{
  "cubes": [
    {
      "name": "Users",
      "title": "Users",
      "meta": {
          "someKey": "someValue",
          "nested": {
            "someKey": "someValue"
          }
      },
      "connectedComponent": 1,
      "measures": [
        {
          "name": "users.count",
          "title": "Users Count",
          "shortTitle": "Count",
          "aliasName": "users.count",
          "type": "number",
          "aggType": "count",
          "drillMembers": ["users.id", "users.city", "users.createdAt"]
        }
      ],
      "dimensions": [
        {
          "name": "users.city",
          "title": "Users City",
          "type": "string",
          "aliasName": "users.city",
          "shortTitle": "City",
          "suggestFilterValues": true
        }
      ],
      "segments": []
    }
  ]
}

​
{base_path}/v1/cubesql

Run the query to the SQL API and get the results.
This endpoint is part of the SQL API.
ParameterDescriptionRequired
queryThe SQL query to run✅ Yes
timezoneThe time zone for this query in the TZ Database Name format, e.g., America/Los_Angeles❌ No
cacheSee cache control. stale-if-slow by default❌ No
Response: a stream of newline-delimited JSON objects. The first object contains the schema property with column names and types, and optionally lastRefreshTime indicating when the data was last refreshed. The following objects contain chunks of the result set under the data property. Each chunk includes one or more rows of the result set.

​
Example

Simple request: 
curl \
  -X POST \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT 123 AS value UNION ALL SELECT 456 AS value UNION ALL SELECT 789 AS value"}' \
  http://localhost:4000/cubejs-api/v1/cubesql
Response: 
{"schema":[{"name":"value","column_type":"Int64"}],"lastRefreshTime":"2025-01-13T12:00:00.000Z"}
{"data":[["789"]]}
{"data":[["123"]]}
{"data":[["456"]]}
Simple request with a query that returns multiple columns: 
curl \
  -X POST \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT full_name, MEASURE(results_race_wins) AS wins, MEASURE(results_average_race_position) AS avg_position FROM session_results GROUP BY 1 ORDER BY 3 LIMIT 5"}' \
  http://localhost:4000/cubejs-api/v1/cubesql
Response: 
{"schema":[{"name":"full_name","column_type":"String"},{"name":"wins","column_type":"Int64"},{"name":"avg_position","column_type":"Double"}],"lastRefreshTime":"2025-01-13T12:00:00.000Z"}
{"data":[["Max VERSTAPPEN","10","3.730769230769231"],["Lando NORRIS","4","4"],["Charles LECLERC","4","4.730769230769231"],["Oscar PIASTRI","3","4.8076923076923075"],["Andrea Kimi ANTONELLI","0","5"]]}

​
{base_path}/v1/pre-aggregations/jobs

Trigger pre-aggregation build jobs or retrieve statuses of such jobs.
This endpoint is part of the Orchestration API.

​
Triggering jobs

ParameterDescriptionRequired
actionUse post to trigger jobs✅
selector.contextsArray of objects, each containing a securityContext✅
selector.timezonesArray of timezones✅
selector.dataSourcesArray of data source names which have pre-aggregations defined❌
selector.cubesArray of cube names which contain pre-aggregations❌
selector.preAggregationsArray of pre-aggregation names❌
selector.dateRangeDate Range tuple [‘range-date-start’, ‘range-date-end’]❌
To trigger pre-aggregation builds, send a POST request with a payload including post as the action and selector properties. The response will contain an array of tokens (identifiers) of triggered jobs. Example request triggering builds of all pre-aggregations defined in all cubes using an empty security context and a UTC timezone: 
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"]
    }
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
Example request triggering builds of all pre-aggregations defined in the orders cube using an empty security context and a UTC timezone: 
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"],
      "cubes": ["orders"]
    }
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
Example request triggering builds of the main pre-aggregation defined in the orders cube using an empty security context and a UTC timezone: 
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"],
      "preAggregations": ["orders.main"]
    }
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
Example request triggering builds of the main pre-aggregation defined in the orders cube within date range with some security context data and an America/Los_Angeles timezone: 
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": { "tenantId": "tenant1" } }],
      "timezones": ["America/Los_Angeles"],
      "preAggregations": ["orders.main"],
      "dateRange": ["2020-01-01", "2020-02-01"]
    }
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
Example response: 
[
  "e9a6a0c55885cea5371348500ce7d7dc",
  "d1329b6c8d152e734fc4dcf7307b1b58",
  "6f4ea38373663fffc4334a576574845b",
  "ea903b10634b2f3141b35a2529870e89"
]

​
Retrieving statuses of jobs

ParameterDescriptionRequired
actionUse get to retrieve statuses of previously triggered jobs✅
tokensArray of tokens returned when triggering jobs✅
resTypeUse object to get a JSON object instead of an array in response❌
To retrieve statuses of previously triggered jobs, send a POST request with a payload including the tokens property. In the status property of the payload, you can get the following statuses:
StatusDescription
scheduledThe job hasn’t run yet
processingThe job is currently running
missing_partitionThe job has failed
doneThe job has successfully completed
Example request: 
curl \
  -d '{
    "action": "get",
    "tokens": [
      "e9a6a0c55885cea5371348500ce7d7dc",
      "d1329b6c8d152e734fc4dcf7307b1b58"
    ]
  }' \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
Example response: 
[
  {
    "token": "e9a6a0c55885cea5371348500ce7d7dc",
    "table": "prod_pre_aggregations.orders_category_and_date_hod0x3hf_03krd5ns_1hop3hn",
    "status": "processing",
    "selector": {
      "cubes": ["orders"],
      "preAggregations": ["orders.category_and_date"],
      "contexts": [{ "securityContext": { "tenant": "tenant_1" } }],
      "timezones": ["UTC"],
      "dataSources": ["default"]
    }
  },
  {
    "token": "d1329b6c8d152e734fc4dcf7307b1b58",
    "table": "prod_pre_aggregations.orders_category_and_date_mzfp445f_r2h2isa5_1hop3hn",
    "status": "processing",
    "selector": {
      "cubes": ["orders"],
      "preAggregations": ["orders.category_and_date"],
      "contexts": [{ "securityContext": { "tenant": "tenant_1" } }],
      "timezones": ["UTC"],
      "dataSources": ["default"]
    }
  }
]

​
Metadata API

Metadata API is only available in Cube Cloud.
These endpoints provide programmatic access to data model metadata for data catalogs, lineage tools, and other integrations. To access these endpoints, you need a JWT token which can be obtained via the Control Plane API.

​
{base_path}/v1/data-sources

Send a GET request to list configured data sources visible to the authenticated user. Example request: 
curl \
  -H "Authorization: Bearer TOKEN" \
  https://example.cubecloud.dev/cubejs-api/v1/data-sources
Example response: 
{
  "data": {
    "data_sources": [
      {
        "name": "default",
        "type": "postgres",
        "database": "analytics",
        "schema": "public"
      }
    ]
  }
}

​
{base_path}/v1/entities

Send a GET request to list all cubes and views in the data model. Results are sorted by type (cubes first), then by name. Query parameters:
ParameterDescriptionRequired
offsetPagination offsetNo
limitMaximum number of items to returnNo
Example request: 
curl \
  -H "Authorization: Bearer TOKEN" \
  "https://example.cubecloud.dev/cubejs-api/v1/entities?limit=10"
Example response: 
{
  "data": {
    "entities": [
      {
        "type": "cube",
        "name": "orders"
      },
      {
        "type": "view",
        "name": "orders_view"
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 2
  }
}

​
{base_path}/v1/entities/{name}

Send a GET request to get detailed metadata for a single cube or view. Path parameters:
ParameterDescription
nameThe cube or view name
Response includes:
  • type - Either cube or view
  • name - The cube or view name
  • title - Human-readable title
  • description - Description from the data model
  • table_references - Data lineage to source tables
  • cube_references - Relationships to other cubes
  • measures - Array of measures with member_references and column_references
  • dimensions - Array of dimensions with is_primary_key flag
Example request: 
curl \
  -H "Authorization: Bearer TOKEN" \
  https://example.cubecloud.dev/cubejs-api/v1/entities/orders
Example response: 
{
  "data": {
    "type": "cube",
    "name": "orders",
    "title": "Orders",
    "description": "Order transactions",
    "table_references": [
      {
        "schema": "public",
        "table": "orders"
      }
    ],
    "cube_references": ["customers", "products"],
    "measures": [
      {
        "name": "count",
        "title": "Count",
        "type": "count",
        "member_references": [],
        "column_references": [
          {
            "schema": "public",
            "table": "orders",
            "column": "id"
          }
        ]
      }
    ],
    "dimensions": [
      {
        "name": "id",
        "title": "Id",
        "type": "number",
        "is_primary_key": true
      },
      {
        "name": "status",
        "title": "Status",
        "type": "string",
        "is_primary_key": false
      }
    ]
  }
}

​
{base_path}/v1/entities/all

Send a POST request to get detailed metadata for multiple cubes and views in one request. Request body:
PropertyTypeDescriptionRequired
cubesarrayArray of cube names to retrieveNo
viewsarrayArray of view names to retrieveNo
Query parameters:
ParameterDescriptionRequired
offsetPagination offsetNo
limitMaximum number of items to returnNo
Example request: 
curl \
  -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cubes": ["orders"], "views": ["orders_view"]}' \
  https://example.cubecloud.dev/cubejs-api/v1/entities/all
Example response: 
{
  "data": {
    "entities": [
      {
        "type": "cube",
        "name": "orders",
        "title": "Orders",
        "measures": [...],
        "dimensions": [...]
      },
      {
        "type": "view",
        "name": "orders_view",
        "title": "Orders View",
        "measures": [...],
        "dimensions": [...]
      }
    ]
  },
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 2
  }
}

​
Health checks

​
/readyz

Reports if the deployment has successfully started. To do so, it will try to test the connection to the default data source. Example of a successful request: 
curl -i http://localhost:4000/readyz
HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"HEALTH"}
Example of a failed response: 
curl -i http://localhost:4000/readyz
HTTP/1.1 500 Internal Server Error
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"DOWN"}

​
/livez

Reports if the deployment is still healthy. This is confirmed by testing any existing connections to data sources. Example of a successful response: 
curl -i http://localhost:4000/livez
HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"HEALTH"}
Example of a failed response: 
curl -i http://localhost:4000/livez
HTTP/1.1 500 Internal Server Error
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"DOWN"}