Today, Vantage is launching API support for Network Flow Reports and Financial Commitment Reports. Users can now programmatically create reports to analyze the source and destination of network traffic that contributes to cloud costs with Network Flow Reports, as well as generate a unified view of all AWS financial commitments with Financial Commitment Reports.

While users could previously create Network Flow Reports and Financial Commitment Reports in the console, large-scale management of multiple reports across many accounts or teams was a tedious process. In addition, customers that use scripts to manage their Vantage reports were unable to do so for these report types. A retrieval endpoint was available for Financial Commitment Reports, but there were no endpoints available to create and update both Financial Commitment and Network Flow Reports.

Now, customers can use the new /network_flow_reports and /financial_commitment_reports API endpoints to programmatically create these reports. With a Vantage API Access Token, customers can now programmatically manage both Network Flow and Financial Commitment Reports, allowing them to create, update, and maintain these reports automatically, without needing to interact with the Vantage console.

These new endpoints are now available to all users, including users in the free tier. To get started with the API, see the API documentation. For more information about Vantage Query Language (VQL) and available fields for reports, see the product documentation.

Frequently Asked Questions

1. What is being launched today?

Vantage is launching the ability to create, update, and delete Network Flow Reports and Financial Commitment Reports via the API. Users can programmatically create reports using Vantage Query Language—or VQL— to define report filter criteria.

2. Who is the customer?

The customer is anyone who would like to automate the setup and maintenance of their Network Flow and Financial Commitment Reports in Vantage.

3. How much does this cost?

There is no additional cost to use the API. It is included in the cost of a Vantage subscription, including users in the free tier.

4. What is VQL?

VQL is a SQL-like syntax, used within the Vantage API, for filtering cloud cost data. It includes a normalized schema across cloud providers and basic filter syntax for creating complex filters. You can use VQL to construct the value for the filter parameter on a report’s Write API endpoint.

5. How do I create a Network Flow Report via the API?

Send the following API request to create a Network Flow Report using the /network_flow_reports endpoint. Details on parameters used in this sample request are provided below:

curl --request POST \
     --url https://api.vantage.sh/v2/network_flow_reports \
     --header 'accept: application/json' \
     --header 'authorization: Bearer TOKEN' \
     --header 'content-type: application/json' \
     --data @- <<EOF
{
  "filter": "(network_flow_logs.az_id = 'use1-az1')",
  "title": "US East 1",
  "date_interval": "last_7_days",
  "groupings": [
    "traffic_category",
    "dstaddr"
  ],
  "flow_weight": "costs",
  "flow_direction": "egress",
  "workspace_token": "wrkspc_123456789"
}
EOF

In the above request:

• The filter parameter limits the report to network flows in use1-az1.
• The date_interval parameter limits the report to the last seven days.
• The groupings parameter has multiple values you can set to group the report. In this example, the report is grouped by traffic category (e.g., cross-az) and destination address.
• The flow_weight can be set to costs or bytes.
• The flow_direction can be set to ingress or egress

The following is returned on a successful 200 response:

{
  "token": "ntflw_lg_rprt_123456789",
  "title": "US East 1",
  "default": false,
  "created_at": "2025-02-04T22:46:01Z",
  "workspace_token": "wrkspc_123456789",
  "created_by_token": "usr_123456789",
  "start_date": "2025-01-28",
  "end_date": "2025-02-03",
  "date_interval": "last_7_days",
  "groupings": "traffic_category,dstaddr",
  "flow_direction": "egress",
  "flow_weight": "costs",
  "filter": "(network_flow_logs.az_id = 'use1-az1')"
}

6. How do I create a Financial Commitment Report via the API?

Send the following API request to create a Financial Commitment Report using the /financial_commitment_reports endpoint. Details on parameters used in this sample request are provided below:

curl --request POST \
     --url https://api.vantage.sh/v2/financial_commitment_reports \
     --header 'accept: application/json' \
     --header 'authorization: Bearer TOKEN' \
     --header 'content-type: application/json' \
     --data @- <<EOF
{
  "title": "ARN-Specific Report",
  "workspace_token": "wrkspc_123456789",
  "filter": "(financial_commitments.provider = 'aws' AND (financial_commitments.commitment_id = 'arn:aws:savingsplans::123456789123:savingsplan/12abc456-d123-1234-aa123-123ab4cd5678'))",
  "date_bucket": "month",
  "on_demand_costs_scope": "discountable",
  "date_interval": "last_3_months"
}
EOF

In the above request:

• The filter parameter limits the report to costs for a specific commitment ARN.
• The date_bucket parameter sets monthly binning on the report.
• The on_demand_cost_scope can be set to discountable or all costs.
• The date_interval parameter limits the report to the last three months.

The following is returned on a successful 200 response:

{
  "token": "fncl_cmnt_rprt_123456789",
  "title": "AWS Commitments",
  "default": false,
  "created_at": "2025-02-04T22:29:28Z",
  "workspace_token": "wrkspc_123456789",
  "user_token": null,
  "start_date": "2024-11-01",
  "end_date": "2025-02-04",
  "date_interval": "last_3_months",
  "date_bucket": "month",
  "groupings": "cost_type",
  "on_demand_costs_scope": "discountable",
  "filter": "(financial_commitments.provider = 'aws' AND (financial_commitments.commitment_id = 'arn:aws:savingsplans::123456789123:savingsplan/12abc456-d123-1234-aa123-123ab4cd5678'))"
}

7. What methods are available with these endpoints?

Both endpoints have associated POST, GET (all reports or a specific report), DELETE, and PUT methods.

8. Who has permission to use the API?

All users can generate Read API keys. You need to have the Editor role or above to modify resources with Write API keys.

9. How do I authenticate with the API?

The Vantage API uses API tokens for authentication. You can create both user and service tokens in the console. An API key can be assigned Read and Write scopes. See the API documentation for details on how to get started with API keys.

10. After I update a report via the API, how long does it take for the report to update in the console?

After you update a report via the API, the updates are immediately available within the console. If a report needs costs regenerated, that process will begin immediately. Any modified filters are also immediately available in the console.

11. Is Terraform support available for these endpoints?

Terraform support will be available soon.

12. Can I view the VQL for an existing report in the UI?

Yes, in the Filters menu on both report types, click the View as VQL button to view the VQL representation of the filter criteria.

13. What are some resources I can use to get started with the API?

Vantage provides multiple resources for getting started with the API:

• The Vantage API documentation site contains information about available API endpoints and provides a tool for running API calls directly on the site.
• The product documentation contains details on how to use VQL.
• The “FinOps as Code” repository contains tutorials and code samples for getting started with the Vantage API.