REST API

Prerequisites

Base path

REST API is used to communicate with Cube.js backend. All requests are prefixed with basePath described in Backend Server Core. By default it's /cubejs-api.

Authentication

Cube.js uses API tokens to authorize requests and also for passing additional security context, which can be used in the queryRewrite property in your cube.js configuration file.

The API Token is passed via the Authorization Header. The token itself is a JSON Web Token, the Security section describes how to generate it.

In the development environment the token is not required for authorization, but you can still use it to pass a security context.

Example request

curl -H "Authorization: EXAMPLE-API-TOKEN" https://example.com/cubejs-api/v1/sql

Continue wait

If the request takes too long to be processed, Cube.js Backend responds with { "error": "Continue wait" } and 200 status code. This is how the long polling mechanism in Cube is implemented. Clients should continuously retry the same query in a loop until they get a successful result. Subsequent calls to the Cube endpoints are idempotent and don't lead to scheduling new database queries if not required by refreshKey. Also, receiving Continue wait doesn't mean the database query has been canceled, and it's actually still being processed by the Cube. Database queries that weren't started and are no longer waited by the client's long polling loop will be marked as orphaned and removed from the querying queue.

Possible reasons of Continue wait:

• The query requested is heavy, and it takes some time for the database to process it. Clients should wait for its completion, continuously sending the same REST API request. continueWaitTimeout can be adjusted in order to change the time Cube waits before returning Continue wait message.
• There are many queries requested and Cube.js backend queues them to save database from overloading.

Error Handling

Cube.js REST API has basic errors and HTTP Error codes for all requests.

Request Span Annotation

For monitoring tools such as Cube Cloud proper request span annotation should be provided in x-request-id header of a request. Each request id should consist of two parts: spanId and requestSequenceId which define x-request-id as whole: ${spanId}-span-${requestSequenceId}. Values of x-request-id header should be unique for each separate request. spanId should define user interaction span such us Continue wait retry cycle and it's value shouldn't change during one single interaction.

Pagination

Cube supports paginated requests for the /v1/load endpoint by including limit and offset parameters in the query. For example, the following query will retrieve rows 101-200 from the Orders cube:

{
  "dimensions": ["Orders.status"],
  "measures": ["Orders.count"],
  "timeDimensions": [
    {
      "dimension": "Orders.createdAt",
      "dateRange": "last year",
      "granularity": "day"
    }
  ],
  "limit": 100,
  "offset": 100
}

API Reference

/v1/load

Get the data for a query.

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 data schema.
  • shortTitle - Short title for visualization usage (ex. chart overlay)
  • type - Data type

Example request:

# Request with http method GET
curl \
 -H "Authorization: EXAMPLE-API-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: EXAMPLE-API-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"
    }
  ],
  annotation:{
    measures:{
      "Users.count":{
        title:"Users Count",
        shortTitle:"Count",
        type:"number"
      }
    },
    dimensions:{},
    segments:{},
    timeDimensions:{}
  }
}

/v1/sql

Get the SQL Code generated by Cube.js to be executed in the database.

Response

• sql - JSON Object with the following properties
  • sql - Formatted SQL query with parameters
  • order - Order fields and direction used in SQL query
  • cacheKeyQueries - Key names and TTL of Cube.js data cache
  • preAggregations - SQL queries used to build pre-aggregation tables

Example request:

curl \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 -G \
 --data-urlencode 'query={"measures":["Users.count"],
 "timeDimensions":[{"dimension": "Users.createdAt","granularity":"day","dateRange":["2019-03-01","2019-03-31"]}]}' \
 http://localhost:4000/cubejs-api/v1/sql

Example response:

{
  sql:{
    sql:[
      "SELECT\n      date_trunc('day', (users.created_at::timestamptz AT TIME ZONE 'UTC')) \"users.created_at_date\", count(users.id) \"users.count\"\n    FROM\n      public.users AS users\n  WHERE (users.created_at >= $1::timestamptz AND users.created_at <= $2::timestamptz) GROUP BY 1 ORDER BY 1 ASC LIMIT 10000",
      [
        "2019-03-01T00:00:00Z",
        "2019-03-31T23:59:59Z"
      ]
    ],
    timeDimensionAlias:"users.created_at_date",
    timeDimensionField:"Users.createdAt",
    order:[
      {
        id:"Users.createdAt",
        desc:false
      }
    ],
    cacheKeyQueries:{
      queries:[
        [
          "select max(users.created_at) from public.users AS users",
          []
        ]
      ],
      renewalThreshold:21600
    },
    preAggregations:[]
  }
}

/v1/meta

Get meta-information for cubes defined in data schema

Response

• cubes - Array of cubes
  • name - Codename of the cube
  • title - Human-readable cube name
  • measures - Array of measures defined within this cube
  • dimensions - Array of dimensions defined within this cube
  • segments - Array of segments defined within this cube
  • connectedComponent - if it has the same value for two cubes, then there is at least one join path between them.

Example request:

curl \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 -G \
 http://localhost:4000/cubejs-api/v1/meta

Example response:

{
  cubes: [
    {
      name: 'Users',
      title: 'Users',
      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: [],
    },
  ];
}

/v1/run-scheduled-refresh

Trigger scheduled refresh run to refresh pre-aggregations. Use it in serverless deployments.

Learn more about scheduled refresh here.

Empty object response if scheduled successfully.

Example request:

curl \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 -G \
 --data-urlencode 'queryingOptions={"timezone":"UTC"}' \
 http://localhost:4000/cubejs-api/v1/run-scheduled-refresh

/readyz

Returns the ready state of the deployment.

Single-tenant: Ensures the orchestration layer is operational and tests the connection to the default dataSource.

Multi-tenant: Tests connections per-tenant. If no connections exist, it will report as successful.

Example request:

curl -i http://localhost:4000/readyz

Successful example response:

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

Failure example response:

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

Returns the liveness state of the deployment. This is confirmed by testing any existing connections to dataSource. If no connections exist, it will report as successful.

curl -i http://localhost:4000/livez

Successful example response:

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

Failure example response:

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