This quickstart guide will walk you through building a complete cost management workflow using the Vantage API. You’ll learn to create folders, generate Cost Reports, and analyze spending data programmatically.
Prerequisites
Base URL All Vantage API v2 requests use the following base URL: https://api.vantage.sh/v2
In this quickstart, we’ll cover the following steps:
Discover Workspaces
First, we’ll retrieve all workspaces your API token has access to.
Create Organization
Set up a folder structure to organize your Cost Reports.
Generate Cost Report
Create a VQL-powered Cost Report with specific filters.
Analyze Data
Retrieve and analyze cost and usage data from your report.
Step 1: Discover Your Workspaces
GET /workspaces Retrieve all workspaces your API token has access to. This endpoint returns workspace tokens and metadata that you’ll use in subsequent API calls.
curl --request GET \ --url https://api.vantage.sh/v2/workspaces \ --header 'accept: application/json' \ --header 'authorization: Bearer ACCESS_TOKEN'
Success Response The response includes pagination links and an array of workspace objects with tokens, names, and configuration details.
{ "links" : { "self" : "https://api.vantage.sh/v2/workspaces" , "first" : "https://api.vantage.sh/v2/workspaces?page=1" , "next" : null , "last" : "https://api.vantage.sh/v2/workspaces?page=1" , "prev" : null }, "workspaces" : [ { "token" : "wrkspc_123445abcde" , "name" : "Management" , "created_at" : "2023-10-01T01:00:56Z" , "enable_currency_conversion" : false , "currency" : "USD" , "exchange_rate_date" : "daily_rate" }, { "token" : "wrkspc_5678fghijk" , "name" : "Marketing" , "created_at" : "2023-10-01T01:00:56Z" , "enable_currency_conversion" : false , "currency" : "USD" , "exchange_rate_date" : "daily_rate" } ] }
Save the workspace tokens from this response. You’ll need them for creating folders and Cost Reports in the next steps.
Step 2: Create an Organized Folder Structure
POST /folders Create a folder to organize your Cost Reports. This helps maintain a clean structure for your cost management workflows.
curl --request POST \ --url https://api.vantage.sh/v2/folders \ --header 'accept: application/json' \ --header 'authorization: Bearer ACCESS_TOKEN' \ --header 'content-type: application/json' \ --data '{ "title": "Team Reports", "workspace_token": "wrkspc_123445abcde" }'
Use the workspace token from Step 1. You can also specify a parent_folder_token to create nested folder structures.
Success Response The response includes the new folder’s token, which you’ll use when creating Cost Reports.
{ "token" : "fldr_123456abcde123" , "title" : "Team Reports" , "parent_folder_token" : null , "saved_filter_tokens" : [], "created_at" : "2023-10-09T13:24:33Z" , "updated_at" : "2023-10-09T13:24:33Z" , "workspace_token" : "wrkspc_123445abcde" }
Save the folder token (fldr_123456abcde123). You’ll need it in the next step to create your Cost Report.
Step 3: Create an Intelligent Cost Report
VQL This step demonstrates the power of Vantage Query Language (VQL) , a flexible query system that lets you filter costs by provider, tags, services, and more. Learn more about VQL syntax .
POST /cost_reports Create a VQL-powered Cost Report that automatically filters AWS production costs.
curl --request POST \ --url https://api.vantage.sh/v2/cost_reports \ --header 'accept: application/json' \ --header 'authorization: Bearer <ACCESS_TOKEN>' \ --header 'content-type: application/json' \ --data '{ "settings": { "include_credits": false, "include_refunds": false, "include_discounts": true, "include_tax": true, "amortize": true, "unallocated": false, "aggregate_by": "cost", "show_previous_period": true }, "chart_type": "line", "date_bin": "cumulative", "title": "AWS Production Costs", "folder_token": "fldr_123456abcde123", "filter": "costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'" }'
The VQL filter costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production' does the following:
costs.provider = 'aws'tags.name = 'environment'environment tagtags.value = 'production'production This creates a focused report showing only your production AWS spending.
Success Response The response includes the Cost Report token and all configuration details. This token is needed for retrieving cost data in the next step.
{ "token" : "rprt_1234a5678b1ab234" , "title" : "AWS Production Costs" , "folder_token" : "fldr_123456abcde123" , "saved_filter_tokens" : [], "filter" : "costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'" , "groupings" : "provider,service" , "settings" : { "include_credits" : false , "include_refunds" : false , "include_discounts" : true , "include_tax" : true , "amortize" : true , "unallocated" : false , "aggregate_by" : "cost" }, "created_at" : "2023-10-09T15:51:48Z" , "workspace_token" : "wrkspc_123445abcde" , "previous_period_start_date" : null , "previous_period_end_date" : null , "start_date" : "2024-07-01" , "end_date" : "2024-07-31" , "date_interval" : "this_month" , "chart_type" : "bar" , "date_bin" : "day" }
Save the report token (rprt_1234a5678b1ab234) - you’ll use it to retrieve cost data in the next step.
Step 4: Analyze Your Cost Data
GET /costs Retrieve detailed cost data from your report with flexible filtering and grouping options. This demonstrates how to extract actionable insights from your cost data.
curl --request GET \ --url 'https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc' \ --header 'accept: application/json' \ --header 'authorization: Bearer <ACCESS_TOKEN>'
Query Parameters Explained
cost_report_tokenstart_date & end_dategroupings=serviceorder=desc
Cost Data Response The response includes pagination links, total cost summary, and detailed cost breakdowns by service.
{ "links" : { "self" : "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc" , "first" : "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc&page=1" , "next" : null , "last" : "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc&page=1" , "prev" : null }, "total_cost" : { "amount" : "1000.11" , "currency" : "USD" }, "costs" : [ { "accrued_at" : "2023-12-31" , "amount" : "300.05" , "currency" : "USD" , "provider" : "aws" , "account_id" : "123456789012" , "service" : "AmazonRDS" }, { "accrued_at" : "2023-12-28" , "amount" : "500.03" , "currency" : "USD" , "provider" : "aws" , "account_id" : "123456789012" , "service" : "AmazonVPC" }, { "accrued_at" : "2023-12-24" , "amount" : "200.03" , "currency" : "USD" , "provider" : "aws" , "account_id" : "123456789012" , "service" : "AmazonECS" } ] }
This data structure is perfect for building cost dashboards, automated alerts, and financial reporting tools.
Bonus: Retrieve Usage Analytics
Usage Data Insights Beyond cost data, the Vantage API provides detailed usage analytics. This is perfect for understanding resource utilization patterns and optimizing your infrastructure.
GET /costs with Usage Data Retrieve both cost and usage data by setting aggregate_by=usage. This provides comprehensive resource utilization insights.
curl --request GET \ --url 'https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&order=desc&settings%5Binclude_credits%5D=false&settings%5Binclude_refunds%5D=false&settings%5Binclude_discounts%5D=true&settings%5Binclude_tax%5D=true&settings%5Bamortize%5D=true&settings%5Bunallocated%5D=false&settings%5Baggregate_by%5D=usage' \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN'
The key parameter here is settings[aggregate_by]=usage which switches from cost aggregation to usage aggregation.
Usage Analytics Response The response includes both cost and usage data, providing comprehensive insights into your resource utilization patterns.
{ "links" : { "self" : "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc" , "first" : "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc&page=1" , "next" : null , "last" : "https://api.vantage.sh/v2/costs?cost_report_token=rprt_1234a5678b1ab234&start_date=2023-12-01&end_date=2023-12-31&groupings=service&order=desc&page=1" , "prev" : null }, "total_cost" : { "amount" : "75455.01" , "currency" : "USD" }, "total_usage" : [ { "amount" : "0.0" , "unit" : "" }, { "amount" : "147793.33" , "unit" : "Hrs" }, { "amount" : "8929.98" , "unit" : "Hours" } ], "costs" : [ { "accrued_at" : "2025-01-06" , "amount" : "885.4577627912" , "currency" : "USD" , "usage" : { "amount" : "910.969248694" , "unit" : "Hrs" }, "provider" : "aws" , "account_id" : "123456789012" , "service" : "AmazonEC2" }, { "accrued_at" : "2025-01-06" , "amount" : "19.4873999955" , "currency" : "USD" , "usage" : { "amount" : "142.9999999995" , "unit" : "Hrs" }, "provider" : "aws" , "account_id" : "123456789012" , "service" : "AmazonEC2" } ] }
This usage data is perfect for building resource optimization tools and capacity planning dashboards.
What You've Accomplished You’ve successfully built a complete cost management workflow using the Vantage API:
Discovered workspaces and retrieved access tokens
Created organized folders for Cost Report management
Generated intelligent Cost Reports using VQL filtering
Analyzed cost data with flexible grouping and filtering
Retrieved usage analytics for resource optimization
