API Reference
Start typing to search…

Quickstart Tutorial

Use this walkthrough to help you get started with the Vantage API.

Prerequisites

Request URL

The base URL for all v2 API requests is as follows:

https://api.vantage.sh/v2

Sample Request Workflow

This workflow simulates a real-world example where you can use the API to automate some of your cloud cost infrastructure management. In this tutorial, you will obtain all workspaces for which you have access, create a folder for Cost Reports, and create a Cost Report using VQL (Vantage Query Language). You will then obtain all costs from the created Cost Report.

View Workspaces (GET /workspaces)

Sample Request

This API call returns all workspaces your API token has access to. The request adds the /workspaces endpoint to the base URL. Specify the ACCESS_TOKEN you obtained from your Vantage account.

curl --request GET \
     --url https://api.vantage.sh/v2/workspaces \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ACCESS_TOKEN'

Sample Response

The response is returned in JSON format. The example response here represents a successful 200 status. The token and human-readable name for each workspace the user's API token has access to are returned in the response.

The below response depicts two workspaces the user has access to in this example: Marketing and Management. You can use the returned workspace tokens as parameter values in additional API requests. 

{
  "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"
    },
    {
      "token": "wrkspc_5678fghijk",
      "name": "Marketing"
    },
  ]
}

Create a Folder (POST /folders)

Sample Request

This call will create a folder for Cost Reports. In the below example, we’ve named the folder Team Reports and have specified the wrkspc_123445abcde workspace ID for Management, which we obtained in the previous example. 

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

Sample Response

The response is returned in JSON format. The example response here represents a successful 201 status. The folder’s unique token is returned in the response. Note that in the initial API call, you can also specify a parent_folder_token. Because we did not specify one here, it returns as null. You can use the returned folder token as a parameter value in additional API requests. 

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

Console View

In the Management workspace, this user now has a folder called “Team Reports.”

Team Reports folder for Cost Reports in the Vantage console

Create a Cost Report (POST /cost_reports)

Sample Request

This call will create a Cost Report in the newly created Team Reports folder. You can create a report with filters using the Vantage Query Language, or VQL. With VQL, you will be able to specify options like provider, cost allocation, and service.

In this particular call, we specify the following parameters:

  • We name the new Cost Report AWS Production Costs.
  • We specify the Team Reports token we obtained before.
  • We use the following query string to create the filter: costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'.
    • This filter will show AWS costs that have an environment tag value of production. 
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 @- <<EOF
{
  "title": "AWS Production Costs",
  "folder_token": "fldr_123456abcde123",
  "filter": "costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'"
}
EOF

Sample Response

The response is returned in JSON format. The example response here represents a successful 201 status. The Cost Report’s unique token is returned in the response. Note that in the initial API call, you can also specify saved_filter_tokens. Because we did not specify one here, it returns empty.

📘

Additional Information

See Filters for related API calls to create and view saved filters.

{
  "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'",
  "created_at": "2023-10-09T15:51:48Z",
  "workspace_token": "wrkspc_123445abcde"
}

Console View

In the Team Reports folder, you should now see a Cost Report called "AWS Production Costs" with the specified filter criteria.

Cost Report with filter for production costs in Vantage console

Get Costs for a Cost Report (GET /costs)

Sample Request

This call will get all costs from the previously created Cost Report. We'll use the token that was returned for the Cost Report we just created.

In this particular call, we specify the following parameters that will all be passed as query parameters:

  • We set cost_report_token=rprt_1234a5678b1ab234.
  • We add a start_date and end_date (in ISO 8601 format) of 2023-12-01 and 2023-12-31, respectively, to show costs only for this particular time frame.
  • We set groupings equal to service to show costs grouped by service.
  • We set order to desc to have the costs sorted by date, in descending order.
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>'

Sample Response

The response is returned in JSON format. The example response here represents a successful 200 status. Each cost associated with the provided parameters is returned in the response. 

{
  "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",
      "service": "AmazonRDS"
    },
    {
      "accrued_at": "2023-12-28",
      "amount": "500.03",
      "currency": "USD",
      "service": "AmazonVPC"
    },
    {
      "accrued_at": "2023-12-24",
      "amount": "200.03",
      "currency": "USD",
      "service": "AmazonECS"
    }
  ]
}

Get Usage Data (GET /costs)

Sample Request

You can also retrieve usage data from the /costs endpoint. This call will get aggregated usage data from the previously created Cost Report. Like the last call, we'll use the token that was returned for the Cost Report we previously created.

In this particular call, we specify the following parameters that will all be passed as query parameters:

  • We set cost_report_token=rprt_1234a5678b1ab234.
  • All other query parameters represent the default values for these parameters.
  • We set the settings[aggregate_by] query parameter to usage.
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'

Sample Response

The response is returned in JSON format. The example response here represents a successful 200 status. total_usage is provided by amount and unit. For each costs item, the usage is also included.

{
  "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"
    }
  ]
}

Updated 10 months ago

What’s Next

You've successfully viewed workspaces, created a folder, and created a Cost Report. You also pulled all costs for the new Cost Report and pulled usage data. Review the documentation for additional endpoints and resources.

    Updated 10 months ago

    What’s Next

    You've successfully viewed workspaces, created a folder, and created a Cost Report. You also pulled all costs for the new Cost Report and pulled usage data. Review the documentation for additional endpoints and resources.