---
title: "GET /v2/billing/costs"
method: GET
path: "/v2/billing/costs"
tags: ["billing"]
---

# GET /v2/billing/costs

`GET /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](https://docs.cloudzero.com/docs/costformation-definition-language-guide#specifying-sources).

**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 parameters

- `start_date` string, required — ISO 8601 datetime string (e.g., 2023-10-26T14:27:46+00:00)
- `end_date` string — ISO 8601 datetime string (e.g., 2023-10-26T14:27:46+00:00)
- `granularity` 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' — Supported periods, e.g. "daily"
- `group_by` DimensionId[]
- `filters` string
- `cost_type` 'billed_cost' | 'discounted_cost' | 'amortized_cost' | 'discounted_amortized_cost' | 'real_cost' | 'on_demand_cost' | 'invoiced_amortized_cost' | 'usage_amount' — https://docs.cloudzero.com/docs/explorer#cost-types
- `align_to_granularity` boolean
- `include_projected_row_count` boolean
- `cursor` string

## Response `200`

Successful Operation

- object
  - `costs` BillingCost[]
    - `usage_date` string — ISO 8601 datetime string (e.g., 2023-10-26T14:27:46+00:00)
    - `cost` number, float
    - `projected_row_count` integer — The number of underlying cost records aggregated into this result row. A single record is a unique set of values across all core dimensions at daily grain. When allocation dimensions split records across multiple targets, this count reflects the total after expansion but before final aggregation. Useful for understanding dimension cardinality and identifying where allocation rules cause large data expansion. Present for daily, weekly, monthly, and yearly granularities; omitted for hourly because the metric is not computed at that granularity. Only included when include_projected_row_count is true.
  - `pagination` Pagination — Supports programmatic pagination
    - `page_count` integer
    - `item_count` integer
    - `total_count` integer
    - `cursor` object
      - `next_cursor` union
        - string
        - unknown
      - `previous_cursor` union
        - string
        - unknown
      - `has_next` boolean
      - `has_previous` boolean

## Other responses

- `400` — Bad Request Error
- `403` — Forbidden
- `410` — Expired Cache Error
- `429` — Rate Limit Error

---

[API](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources.md) · [All operations](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cloudzero/cloudzero-api-v2-resources/revisions/fd805a0e75e5/schema)