Skip to main content
GET
/
costs
Get costs for cost report or VQL filter
curl --request GET \
  --url https://api.vantage.sh/v2/costs \
  --header 'Authorization: Bearer <token>'
{
  "links": {
    "self": "https://api.vantage.sh/v2/costs?cost_report_token=rprt_ea7dbb4f5783d677",
    "first": "https://api.vantage.sh/v2/costs?cost_report_token=rprt_ea7dbb4f5783d677&page=1",
    "next": null,
    "last": null,
    "prev": null
  },
  "total_cost": {
    "amount": "500.0",
    "currency": "USD"
  },
  "costs": [
    {
      "accrued_at": "2023-06-05",
      "amount": "100.0",
      "currency": "USD",
      "provider": "aws",
      "account_id": "mock_56789",
      "service": "AmazonSNS"
    },
    {
      "accrued_at": "2023-06-04",
      "amount": "100.0",
      "currency": "USD",
      "provider": "aws",
      "account_id": "mock_56789",
      "service": "AmazonSNS"
    },
    {
      "accrued_at": "2023-06-03",
      "amount": "100.0",
      "currency": "USD",
      "provider": "aws",
      "account_id": "mock_56789",
      "service": "AmazonSNS"
    },
    {
      "accrued_at": "2023-06-02",
      "amount": "100.0",
      "currency": "USD",
      "provider": "aws",
      "account_id": "mock_56789",
      "service": "AmazonSNS"
    },
    {
      "accrued_at": "2023-06-01",
      "amount": "100.0",
      "currency": "USD",
      "provider": "aws",
      "account_id": "mock_56789",
      "service": "AmazonSNS"
    }
  ]
}

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, 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
​
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]
string
default:cost

Results will aggregate by cost or usage.

​
settings[show_previous_period]
boolean
default:true

Results will show previous period costs or usage comparison.

Response

Costs model

​
links
object
​
total_cost
object

The sum of all costs for the CostReport for the requested period, rounded to 2 decimal places, alongside the ISO 4217 currency code.

​
total_usage
object

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

​
costs
object[]