Skip to content

HTTP API Usage provides an HTTP API that allows users to retrieve information about builds, consumed CPU hours and more. The available API endpoints are detailed here.


To start using the API, you first need to create an authorization token. The tokens used by are based on Biscuit, giving users a flexible way of setting up advanced authorization policies for their accounts. The Biscuit support is something that will be expanded upon and documented in the future. For now, you can treat the authorization tokens as plain API keys, ignoring the fact that they are Biscuit tokens.

Start out by creating a new authorization token in the shell like this:> tokens create --read-only

It is strongly recommended that you use the --read-only option to create a token with limited permissions. So far, the API only provides read-only operations, so it doesn't hurt limiting your tokens this way.

By default, tokens are valid for 1000 days. You can also set shorter expiration times, see tokens create --help.

The tokens you create are not stored in It is your responsibility to store your tokens safely. User-available token revocation is not possible at the moment, but will be in the future. If you need to revoke tokens, please contact [email protected].

Usage Example

Using the token we created above we can access the API with curl like this:

$ curl -s \
    -H 'Authorization: Bearer EpABCiYKB2FjY291bnQYAyIJCgcIgAgSAhABMg4KDAoCCBsSBggDEgIYABIkCAASIFeRyO2t1bxV2ZlLJKkp4S97nCyAz1ieyrCLv_RzYI0EGkCYCkIllHyVVnfZwyh0zxcKO-iqgtHkkaudYvZE9wL6otfeMe-ATkGh0Gkz_KyLt_YEbt__X5DRJ6Tj_41Z35APIiIKIHmZTFwQzdy2GZadSXRFYscLTHnbb_spQgLonsqos2tv'

  "billable_cpu_seconds": 316,
  "billable_build_count": 251

In the above example, we used the /usage API endpoint, which returns information about how many CPU hours you have used during a given period. To see all available endpoints and their parameters, see the API reference.