Skip to main content
GET
Get costs for cost report or VQL filter

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

cost_report_token
string

The CostReport token.

filter
string

The VQL filter to apply to the costs. If this is supplied you do not need cost_report_token.

workspace_token
string

The token of the Workspace to query costs from. Ignored if 'cost_report_token' is set. Required if the API token is associated with multiple Workspaces.

start_date
string

First date you would like to filter costs from. ISO 8601 formatted.

end_date
string

Last date you would like to filter costs to. ISO 8601 formatted.

groupings
string[]

Group the results by specific field(s). Defaults to provider, service, account_id. Valid groupings: account_id, billing_account_id, charge_type, cost_category, cost_subcategory, provider, region, resource_id, service, tagged, usage_unit, tag:<tag_value>. If providing multiple groupings, join as comma separated values: groupings=provider,service,region

order
enum<string>
default:desc

Whether to order costs by date in an ascending or descending manner.

Available options:
asc,
desc
limit
integer<int32>

The amount of results to return. The maximum is 5000.

page
integer<int32>

The page of results to return.

date_bin
enum<string>

The date bin of the costs. Defaults to the report's default or day.

Available options:
day,
week,
month,
quarter,
hour
settings[include_credits]
boolean
default:false

Results will include credits.

settings[include_refunds]
boolean
default:false

Results will include refunds.

settings[include_discounts]
boolean
default:true

Results will include discounts.

settings[include_tax]
boolean
default:true

Results will include tax.

settings[amortize]
boolean
default:true

Results will amortize.

settings[unallocated]
boolean
default:false

Results will show unallocated costs.

settings[aggregate_by]
enum<string>
default:cost

Results will aggregate by cost, usage, or count.

Available options:
cost,
usage,
count
settings[show_previous_period]
boolean
default:true

Results will show previous period cost, usage, or count comparison.

Response

Costs model

total_cost
object
required
costs
object[]
required
total_usage
object[]

The sum of all usage for the CostReport for the requested period, rounded to 2 decimal places, grouped by usage unit.

total_count
integer<int64> | null

The sum of the date-binned counts. Present when settings.aggregate_by is 'count'.

counts
object[]

Distinct Group By permutation counts for the full requested period, unaffected by page and limit. Bins without cost are omitted. Present when settings.aggregate_by is 'count'.