Getting Started with the Cloudability API

Our Public API

The Cloudability API implementation is based on REST principles. You should find the interface to be predictable with use of resource-oriented URLs and reliance on standard HTTP features that are generally understood by off-the-shelf HTTP clients. For example the API relies on HTTP basic auth for authentication, HTTP verbs (methods such as GET,PUT...) for actions and standard HTTP response codes to indicate API errors or otherwise. By default all API responses are returned as JSON, but other formats such as CSV are available by setting the relevant HTTP media type.

Views and the API

Cloudability employs a Views System to give our customers a tailored experience as they make use of all aspects of our tool. This system is also in place within our API and has the following characteristics

  • When making API requests we will automatically respect the default view attached to your user
  • If you wish to switch to a different view with your API request you can use the viewId query parameter to declare your desired view. Example ?viewId=2970
  • If you wish to apply no view at all, i.e run the query across all data, then apply viewId with a value of zero. Example: ?viewId=0
  • Note: Restricted users will only be able to apply views they have access to.

Special Notes

Note that sort and filtering functionality as documented below is not available for all endpoints. If you visit the individual endpoint documentation it will be noted whether this is supported or not.


Every Cloudability user can go to their preferences and enable access to our public API. Here you'll receive a personalised API key which forms a part of our Basic Auth requirements.

Additionally, permissions for API interactions to create, update, read, and delete correspond with Cloudability user permissions. For example, only Cloudability Admins can provision a new Container cluster for data collection, while all Cloudability Users with API access can get an existing Container cluster's resource usage information.

API interactions with cloudability are secured over https. Your token forms the username component of the basic auth header. So the authorization header would look something like:

Authorization: Basic <You_API_Key Base64 encoded>

curl -u 'Your_API_Key:'
  • Note the above API returns information about our supported cloud vendors

API Interactions

Response Format

All successful responses will be in the following format

    result: {} or [],
    meta: {},
  • result will contain the results/payload for the call.
  • Ancillary information (such as pagination breakdowns etc) will exist in the meta attribute if relevant.
  • Primitive values will be null if no value is present. i.e. numbers, strings, etc.
  • Objects and arrays will return their empty states if no value is present. i.e. {} and []
  • Dates are ISO8601 standard with the format of "YYYY-MM-DD"


Content-Type: application/json (for POST and PUT requests)
Accept: application/json (for GET) for all endpoints
Accept: text/csv (for GET) is supported by some endpoints
Authorization: Basic <cldy_token>


Not all endpoints support pagination - for ones that don't all records will be returned always. For endpoints which do support pagination, by default the first 50 matching records will be returned only.

The limit and offset parameters must be used together when attempting pagination. When they're used, the result set will be restricted to the "limit" amount from the "offset" value. These parameters can be used with sort (below) to obtain a specific result set.

limit - defaults to 50 (only 50 returned)
offset - defaults to 0 (start of records)
example - /views?limit=5&offset=20


Use the sort query parameter to sort your results. Use '-' for descending and '+' for ascending prepended to the attribute you wish to sort with. For example with the portfolio endpoint we could sort against the 'end' attribute to order by oldest or newest RI.

example: /portfolio/ec2?sort=-end

example: /portfolio/ec2?sort=%2bend (making sure to URL encode correctly the '+' symbol)


When you use the filter query parameter, you supply a dimension you want to filter on, followed by the filter expression.

Filtered queries restrict the rows that get included in the result. Each row in the result is tested against the filter: if the filter matches, the row is retained and if it doesn't match, the row is dropped. Please note, client libraries automatically URL encode the filter operators. However, if you make requests directly to the protocol, you must explicitly URL encode filter operators that are listed in the table below. Also, filtering occurs before any dimensions are aggregated, so that the returned metrics represent the total for only the relevant records.

Filter syntax (name operator expression):

name — the name of the dimension on which to filter.
operator — defines the type of filter match to use.
  == - equals
  != - not equals
  > - greater than
  < - less than
  >= - greater than or equal to
  <= - less than or equal to
  [email protected] - contains
  [email protected] - does not contain
expression — states the values included in the results.

To apply multiple filters to a request delimit with commas in one filter parameter. See examples below:

example: /portfolio/ec2?filter=state==active (check if the state is active)

example: /portfolio/ec2?filter=state==retired (check if the state is retired)

example: /portfolio/ec2?filter=end<1541803776000 (check if end is less than 1541803776000)

example: /portfolio/ec2?filter=end>1541803776000 (check if end is greater than 1541803776000)

example: /portfolio/ec2?filter=state==active,end>1541803776000 (apply multiple filters)

Our Examples

The documentation for each end point will include a number of examples which will hopefully give users a sense of how to interact with the API and generate ideas for further use cases. We expect that our customers will have many numerous client applications and platforms that they will integrate with Cloudability, but for the purpose of simplicity we will provide our examples using cURL for HTTP interactions and jq for parsing JSON. Both of these CLI tools are widely used and can be easily employed to interact with a RESTful API.