Quickstart

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

A Vantage account with at least one provider integration
A Vantage API access token with Read and Write scopes enabled

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.

This quickstart focuses on API-native resource creation and data retrieval. If you need a point-in-time CSV (including a CSV export in the FOCUS schema) or PDF that mirrors a Cost Report in the UI, use the Cost Report export flow instead.

Step 1: Discover Your Workspaces

Request
Response

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.

If your account uses multiple workspaces or team-scoped service tokens, choose a workspace that your token can access and use that workspace_token consistently in your create requests.

Step 2: Create an Organized Folder Structure

Request
Response

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.

Request
Response

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'"
}'

VQL Filter Breakdown

The VQL filter costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production' does the following:

costs.provider = 'aws' - Only includes AWS costs
tags.name = 'environment' - Filters for resources with an environment tag
tags.value = 'production' - Only includes resources tagged as 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

Request
Response

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_token - Uses the report token from Step 3
start_date & end_date - ISO 8601 date range for filtering
groupings=service - Groups costs by AWS service (EC2, RDS, etc.)
order=desc - Sorts by date in descending order (newest first)

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.

Request
Response

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

Getting Started

About the API

API Reference

OpenAPI Specification

Prerequisites

Base URL

Step 1: Discover Your Workspaces

GET /workspaces

Success Response

Step 2: Create an Organized Folder Structure

POST /folders

Success Response

Step 3: Create an Intelligent Cost Report

VQL

POST /cost_reports

Success Response

Step 4: Analyze Your Cost Data

GET /costs

Cost Data Response

Bonus: Retrieve Usage Analytics

Usage Data Insights

GET /costs with Usage Data

Usage Analytics Response

What You've Accomplished

​Prerequisites

Base URL

​Step 1: Discover Your Workspaces

GET /workspaces

Success Response

​Step 2: Create an Organized Folder Structure

POST /folders

Success Response

​Step 3: Create an Intelligent Cost Report

VQL

POST /cost_reports

Success Response

​Step 4: Analyze Your Cost Data

GET /costs

Cost Data Response

​Bonus: Retrieve Usage Analytics

Usage Data Insights

GET /costs with Usage Data

Usage Analytics Response

What You've Accomplished

Prerequisites

Step 1: Discover Your Workspaces

Step 2: Create an Organized Folder Structure

Step 3: Create an Intelligent Cost Report

Step 4: Analyze Your Cost Data

Bonus: Retrieve Usage Analytics