/v2/billing/costs

get

https://api.cloudzero.com/v2/billing/costs

This API will return cost data according to the parameters passed in.

Rate Limit: 60 requests/day.
Timeout: 30 seconds.
Pagination: Results are paginated in blocks of 10,000 records.
- Using cursors for pagination doesn't affect the rate limit.
- You have 24 hours to page through your results before you will need to rerun your query.
- While using pagination, your results will be static as of run time.
This data is statically sorted as usage_date asc.

NOTE: The Dimension IDs referenced within this document are the IDs by which you reference dimensions when authoring in CostFormation. You can read more about this here.

API Call Examples For the following examples, the following updates need to be made before running:

Replace <START_DATE_HERE> with a properly formatted start date (2023-10-26 or (date and time encoded) 2023-10-26T14%3A27%3A46%2B00%3A00)
Replace <GRANULARITY_VALUE_HERE> with the desired granularity (hourly, daily, weekly, monthly, yearly)

Real Cost Grouped by Account and Service, Filtered by Cloud Provider = AWS

https://api.cloudzero.com/v2/billing/costs?start_date=<START_DATE_HERE>&granularity=<GRANULARITY_VALUE_HERE>&group_by=Account&group_by=Service&filters=%7B%22CloudProvider%22%3A%20%5B%22AWS%22%5D%7D&cost_type=real_cost

Real Cost Grouped by Account and Service Detail Dimension, Filtered by Service = AmazonS3

https://api.cloudzero.com/v2/billing/costs?start_date=<START_DATE_HERE>&granularity=<GRANULARITY_VALUE_HERE>&group_by=Account&group_by=CZ%3ADefined%3AServiceDetail&filters=%7B%22Service%22%3A%20%5B%22AmazonS3%22%5D%7D&cost_type=real_cost

Real Cost Grouped by by Account Name and Service

https://api.cloudzero.com/v2/billing/costs?start_date=<START_DATE_HERE>&granularity=<GRANULARITY_VALUE_HERE>&group_by=User%3ADefined%3AAccountName&group_by=Service&cost_type=real_cost

Query Params

start_date

string

required

Defaults to 2025-01-01T00:00:00Z

ISO 8601 datetime string from which to view costs.

When using this form: 2023-10-26T14:27:46+00:00
When using HTTP URL (This must be encoded!):
- Encoded: 2023-10-26T14%3A27%3A46%2B00%3A00
- Decoded: 2023-10-26T14:27:46+00:00

end_date

string

Defaults to 2025-01-01T00:00:00Z

ISO 8601 datetime string until which to view costs (defaults to current date and time).

When using this form: 2023-10-26T14:27:46+00:00
When using HTTP URL (This must be encoded!):
- Encoded: 2023-10-26T14%3A27%3A46%2B00%3A00
- Decoded: 2023-10-26T14:27:46+00:00

granularity

string

enum

Defaults to daily

Supported periods, e.g. "daily"

Allowed:

group_by

array of objects

Dimension ID(s) by which to group the results. This is a multi-value query parameter, pass it more than once to specify multiple values.

When using this form: Region and Tag:Name
When using HTTP URL: &group_by=Region&group_by=Tag:Name

group_by

filters

string

An encoded JSON mapping of Dimension IDs to values by which to filter the results. The keys are dimension IDs; they may be negated with a '!' prefix. For a list of the Dimension IDs, see the CostDefinition Language Reference.

When using this form (Do not encode):
- {"Region": ["us-east-1"], "!Account": ["123456789012"]}
When using HTTP URL (This must be encoded!):
- Encoded: %26filters%3D%7B%22Region%22%3A%20%5B%22us-east-1%22%5D%2C%20%22%21Account%22%3A%20%5B%22123456789012%22%5D%7D
- Decoded: &filters={"Region": ["us-east-1"], "!Account": ["123456789012"]}

cost_type

string

enum

Defaults to real_cost

https://docs.cloudzero.com/docs/explorer#cost-types

cursor

string

Allows you to page forward and back in your results. NOTE: This must be URL Encoded!

See the Pagination section of the API Reference for more information!

Responses

200Successful Operation

400Bad Request Error

403Forbidden

410Expired Cache Error

429Rate Limit Error