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 Token for requests' authorization and also for passing additional user context, which could be used in the USER_CONTEXT object in the Data Schema.

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 user 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. To get the data requested, simply retry your request a bit later.

Possible reasons of Continue wait:

The query requested is heavy and it takes some time for the database to process it.
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.

Status	Error response	Description
400	Error message	General error. It may be a database error, timeout, or other issue. Check error message for details.
403	Authorization header isn't set	You didn't provide an auth token. Provide a valid API Token or disable authorization.
403	Invalid token	The auth token provided is not valid. It may be expired or have invalid signature.
500	Error message	Cube.js internal server error. Check error message for details.

API Reference

/v1/load

Get data for a query.

Parameter	Description
query	URL encoded Cube.js Query

Response

query - The query passed via params
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:

curl \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 -G \
 --data-urlencode '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.

Parameter	Description
query	URLencoded Cube.js Query

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

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",
          drillMembers:[
            "Users.id",
            "Users.city",
            "Users.createdAt"
          ]
        }
      ],
      dimensions:[
        {
          name:"Users.city",
          title:"Users City",
          type:"string",
          aliasName:"users.city",
          shortTitle:"City",
          suggestFilterValues:true
        }
      ],
      segments:[]
    }
  ]
}