VQL for Cost Reports

If you need help constructing a VQL query, navigate to a Cost Report and open the Filters menu. Create a filter and click View as VQL at the top of the Filters menu to see a filter’s VQL representation. You can also edit VQL directly and click Apply to update the filter.

Cost Reports VQL Schema

VQL comprises two namespaces: costs and tags, which represent the available filters on Cost Reports in the Vantage console. To reference a filter, use the following syntax: namespace.field (e.g., costs.provider or tags.name).

Namespace	Field	VQL Example
`costs`	`provider` (optional)	Filter across all providers or combine specific providers
`costs`	`allocation`	Cost allocation example
`costs`	`region`	Region example
`costs`	`marketplace`	Marketplace example
`costs`	`account_id`	Account ID example
`costs`	`provider_account_id`	Provider account ID example
`costs`	`service`	Service example
`costs`	`category`	Category example
`costs`	`subcategory`	Subcategory example
`costs`	`resource_id`	Resource example
`costs`	`charge_type`	Charge Type example
`costs`	`usage_unit`	Usage Unit example
`tags`	`name`	Tags name/value example
`tags`	`value`	Untagged example

costs.provider is optional. Omit it to filter across every connected provider in a single query—see Filter Across All Providers. Provider-specific fields (such as AWS costs.marketplace) only apply when costs.provider is included for that provider.

Availability of the fields listed above varies among different cloud providers. For a comprehensive list of available fields per provider, including the source billing field each one maps to, see the Data Dictionary.

Keywords

VQL includes a set of keywords to create complex filter conditions. These keywords function similar to their SQL equivalents.

Keyword	Description	VQL Sample	Explanation
`AND`	Logical AND operator	`costs.provider = 'aws' AND costs.service = 'EC2'`	This example filters AWS costs for the EC2 service, where both conditions must be true.
`OR`	Logical OR operator	`costs.provider = 'azure' OR costs.provider = 'aws'`	This example retrieves costs from either Azure or AWS. At least one condition must be true.
`IN`	Used to compare against an array list	`costs.provider = 'azure' AND costs.account_id IN ('account-1', 'account-2')`	This example filters based on a list of account IDs, returning data for the specified accounts. You can also use `IN` along with a special syntax for filtering by multiple tags. See Filter by Multiple Tags for details. `costs.provider IN (...)` is supported and is expanded into one filter set per provider. `costs.provider NOT IN (...)` is not supported.
`LIKE`	Performs string comparisons	`costs.provider = 'gcp' AND tags.name = 'environment' AND tags.value LIKE '%prod%'`	This example selects data where the tag value contains `prod`, such as `production-1`.
`NOT`	Represents negation	`costs.provider = 'aws' AND costs.region NOT IN ('us-east-1', 'us-east-2')`	This example filters out data from both specified regions, providing all AWS costs not in these regions. Use `NOT IN` to specify a list of single or multiple values. You can also use the `!=` or `<>` operators for “is not.” `costs.provider = 'aws' AND costs.region != 'us-east-1'` You can use `NOT LIKE` to perform string comparisons: `costs.provider = 'gcp' AND tags.name = 'environment' AND tags.value NOT LIKE '%prod%'`
`~*`	Flexible match operator for tag values	`costs.provider = 'aws' AND (tags.name = 'teams' AND tags.value ~* 'Team A')`	Searches for all items where the tag value loosely matches `Team A`, ignoring case, whitespace, hyphens, and punctuation.
`!~*`	Negated flexible match operator for tag values	`costs.provider = 'aws' AND (tags.name = 'teams' AND tags.value !~* 'Team A')`	Filters out all items where the tag value loosely matches `Team A`, ignoring case, whitespace, hyphens, and punctuation.

With these keywords, you can construct complex filter conditions in VQL, providing flexibility and precision when querying and analyzing cloud cost data.

Syntax

You can think of VQL in its current iteration as the WHERE clause of a SQL query. By combining the schema and keywords above with parentheses, you can form complex filter operations, such as:

(costs.provider = 'mongo' AND costs.allocation = 1.0 AND (costs.service = 'REALM' AND costs.resource_id IN ('s3'))) OR (costs.provider = 'aws' AND costs.allocation = 1.0 AND costs.account_id IN ('123456798'))

VQL Examples

The following examples cover common use cases for VQL.

Filter Across All Providers

You can omit costs.provider to filter across every connected provider in a single query. This is useful for multi-cloud questions where the same filter logic should apply regardless of where the cost was incurred—for example, finding all costs tagged with a specific team across AWS, Azure, GCP, and any other connected providers.

tags.name = 'Team' AND tags.value = 'Data Engineering'

The query above returns costs from every connected provider that has a matching tag, without you having to repeat the filter for each one. The same pattern works for any field in the Cost Reports VQL Schema. You can still include costs.provider when you want to scope a filter to a single provider; this feature only removes the requirement to do so. Provider-specific fields (such as AWS-only costs.marketplace) still need costs.provider to be set for that provider.

An entirely empty filter (no rules at all) is also valid VQL and is equivalent to filtering across every connected provider with no constraints. This is the representation used for the default unfiltered All Resources Cost Report and for any other report whose filter set spans all providers with no rules applied. If you click View as VQL on such a report, the query string will be empty.

Filtering across all providers queries data from every connected provider, which is more work than filtering by a single provider. The impact is most pronounced on tag-heavy queries and Virtual Tag rules. For guidance on scoping providerless filters efficiently, including granular filters, exact-match operators, and when to prefer per-provider OR over a fully providerless query, see Best Practices for Filtering Across All Providers in the Tagging documentation.

Combining Providers

To reference a Custom Provider in VQL queries, navigate to the Integrations page. Use the displayed Provider ID (e.g., custom_provider:accss_crdntl_123a45bfdaf38765).

Filter for provider costs associated with either MongoDB Atlas or AWS.

costs.provider = 'mongo' OR costs.provider = 'aws'

Cost Allocation

Set cost allocation to 0.5.

costs.provider = 'gcp' AND costs.allocation = 0.5

Costs from a List of Regions

Filter for Snowflake costs in two regions. Note that you will need to use the region code, such as us-east-1 in the case of AWS, or AWS_US_EAST_1 in the case of Snowflake, below.

costs.provider = 'snowflake' AND costs.region IN ('AWS_US_EAST_1', 'AWS_US_EAST_2')

Get Marketplace Transactions

Retrieve costs associated with the AWS Marketplace.

costs.provider = 'aws' AND costs.marketplace = true

Costs by Account ID

Costs for a specific set of services and account ID.

costs.provider = 'aws' AND costs.account_id = '123456758' AND costs.service IN ('Amazon Relational Database', 'Amazon Elastic Compute Cloud - Compute')

Costs by Provider Account ID

The following example represents costs from a specific AWS billing account or costs from a specific Azure subscription.

(costs.provider = 'aws' AND costs.provider_account_id = 'abcd1234') OR (costs.provider = 'azure' AND costs.provider_account_id = 'abcd1234')

Per-Resource Costs and Costs by Service

Resource costs require both provider and service in addition to the resource_id.

costs.provider = 'aws' AND costs.service = 'Amazon Relational Database Service' AND costs.resource_id = 'arn:aws:rds:us-east-1:123456789:db:primary-01'

Multiple Resource IDs

costs.provider = 'aws' AND costs.service = 'Amazon Relational Database Service' AND costs.resource_id IN ('arn:aws:rds:us-east-1:123456789:db:primary-01', 'arn:aws:rds:us-east-1:123456789:db:primary-02')

Costs by Specific Category

Filter costs to see a specific cost category. Category costs require provider, service, and category. To filter across all services, use costs.service = '*' as a wildcard.

costs.provider = 'fastly' AND costs.service = 'CDN' AND costs.category = 'Data Transfer'

Filter by category across all services for a provider:

costs.provider = 'aws' AND costs.service = '*' AND costs.category = 'Data Transfer'

Costs by Specific Subcategory

Filter costs by a specific service and subcategory. Subcategory costs require provider, service, and subcategory. To filter across all services, use costs.service = '*' as a wildcard.

costs.provider = 'aws' AND costs.service = 'AWS Certificate Manager' AND costs.subcategory = 'USE1-PaidPrivateCA'

Filter by subcategory across all services for a provider:

costs.provider = 'aws' AND costs.service = '*' AND costs.subcategory = 'DataTransfer-Out-Bytes'

Cost by Charge Type

Filter costs by a specific charge type.

costs.provider = 'aws' AND costs.charge_type = 'Usage'

Filter by Usage Unit

Filter AWS costs to include only usage measured in hours.

costs.provider = 'aws' AND costs.usage_unit = 'Hours'

You can omit costs.provider to apply the Usage Unit filter across every connected provider, or use IN to match multiple units.

The Vantage console normalizes Usage Unit labels for display, but VQL matches the underlying value exactly. Build the filter in the console and click View as VQL to copy the correct value when a displayed label differs from the provider’s stored value. See Understand Usage Units and the Data Dictionary for more information.

Filter by Tag

Filter by Single Tag

Filter costs based on a specific tag, such as environment, with the value production, in AWS.

costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'

Filter for Multiple Values from a Single Tag Key

If you want to filter for multiple tag values that are tied to one tag key (e.g., costs tagged with the team tag of mobile and data), use the below syntax.

costs.provider = 'aws' AND tags.name = 'team' AND tags.value IN ('mobile', 'data')

Filter by Multiple Tags

If you want to filter for resources that have more than one tag associated, you can use the syntax shown in the example below.

costs.provider = 'aws' AND (tags.name, tags.value) IN (('environment', 'staging'), ('team', 'engineering'))

This example filters for resources that are tagged with the environment tag with a value of staging as well as the team tag with a value of engineering. This filter is the same as creating the following manual filter in the console.

Filter for Matching Tags Using `LIKE`

costs.provider = 'azure' AND (tags.name = 'environment' AND tags.value LIKE '%prod%')

Filter for Tags Using Flexible Matching

costs.provider = 'azure' AND (tags.name = 'Team' AND tags.value ~* 'Team A')

Matches on applied tag values, such as TeamA, team-a, and team_a to a single Team A tag value. See the Flexible Match documentation for details.

Filter for Untagged Resources

On providers that have a Not Tagged/Not Labeled filter option in the console, you can use the below VQL to see untagged resources across every connected provider.

tags.name = NULL

If you only want to check a specific subset of providers, list them explicitly with OR:

(costs.provider = 'aws' AND tags.name = NULL) OR (costs.provider = 'azure' AND tags.name = NULL) OR (costs.provider = 'gcp' AND tags.name = NULL)

Troubleshooting

If you are receiving an error when trying to complete a query, check the following troubleshooting tips.

Each provider exposes certain names to the API. Those names are normalized within the schema. Check the Data Dictionary for normalized field names.
Query parameter values should be wrapped in single quotes.

Click to view examples

THIS WORKS

costs.provider='aws'

THIS DOES NOT WORK

costs.provider="aws"

Currently, there is a limitation where AND and OR are not supported together in a single “query group.”

Click to view examples

THIS WORKS

(costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'dev') OR (costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'prod')

THIS DOES NOT WORK

costs.provider = 'aws' AND ((tags.name = 'environment' AND tags.value = 'dev') OR (tags.name = 'environment' AND tags.value = 'prod'))

The costs.provider field is optional. Omit it to filter across every connected provider in a single query, or include it to scope the filter to a specific provider. See Filter Across All Providers for details and performance considerations.

Click to view examples

BOTH WORKFilter across every connected provider:

costs.service = 'CDN'

Filter for a specific provider:

costs.provider = 'fastly' AND costs.service = 'CDN'

Provider-specific fields only apply when costs.provider is set for that provider. For example, AWS exposes costs.marketplace, but it has no effect when used without an AWS provider scope.

Click to view examples

THIS WORKS

costs.provider = 'aws' AND costs.marketplace = true

THIS DOES NOT WORK

costs.marketplace = true

costs.marketplace is only meaningful for AWS, so it must be paired with costs.provider = 'aws'.

The costs.provider field supports IN (which is expanded into one filter set per provider), but does not support NOT IN.

Click to view examples

THIS WORKS

costs.provider IN ('aws', 'azure')

Vantage expands costs.provider IN ('aws', 'azure') into the equivalent of two filter sets, one per provider. You can also combine IN on costs.provider with provider-specific filters using OR:

(costs.provider = 'aws' AND costs.account_id IN ('123456789', '987654321')) OR (costs.provider = 'azure' AND costs.account_id IN ('account-1', 'account-2'))

THIS DOES NOT WORK

costs.provider NOT IN ('aws', 'azure')

Resource costs require both provider and service in addition to the resource ID.

Click to view examples

THIS WORKS

costs.provider = 'aws' AND costs.service = 'Amazon Relational Database Service' AND costs.resource_id = 'arn:aws:rds:us-east-1:123456789:db:primary-01'

THIS DOES NOT WORK

costs.provider = 'aws' AND costs.resource_id = 'arn:aws:rds:us-east-1:123456789:db:primary-01'

Category and subcategory costs also require provider and service. To filter across all services, use costs.service = '*' as a wildcard.

Click to view examples

THESE WORK

costs.provider = 'fastly' AND costs.service = 'CDN' AND costs.category = 'Data Transfer'

costs.provider = 'aws' AND costs.service = 'AWS Certificate Manager' AND costs.subcategory = 'USE1-PaidPrivateCA'

costs.provider = 'aws' AND costs.service = '*' AND costs.category = 'Data Transfer'

THESE DO NOT WORK

costs.provider = 'fastly' AND costs.category = 'Data Transfer'

costs.provider = 'aws' AND costs.subcategory = 'USE1-PaidPrivateCA'

Get Started

Account & Security

AI, Terraform, & Developer Tools

Provider Integrations

App Integrations

Revenue & Finance Integrations

Cost Reporting Features

Financial Planning Features

VQL for Cost Reports

Cost Reports VQL Schema

Keywords

Syntax

VQL Examples

Filter Across All Providers

Combining Providers

Cost Allocation

Costs from a List of Regions

Get Marketplace Transactions

Costs by Account ID

Costs by Provider Account ID

Per-Resource Costs and Costs by Service

Multiple Resource IDs

Costs by Specific Category

Costs by Specific Subcategory

Cost by Charge Type

Filter by Usage Unit

Filter by Tag

Filter by Single Tag

Filter for Multiple Values from a Single Tag Key

Filter by Multiple Tags

Filter for Matching Tags Using `LIKE`

Filter for Tags Using Flexible Matching

Filter for Untagged Resources

Troubleshooting

​Cost Reports VQL Schema

​Keywords

​Syntax

​VQL Examples

​Filter Across All Providers

​Combining Providers

​Cost Allocation

​Costs from a List of Regions

​Get Marketplace Transactions

​Costs by Account ID

​Costs by Provider Account ID

​Per-Resource Costs and Costs by Service

​Multiple Resource IDs

​Costs by Specific Category

​Costs by Specific Subcategory

​Cost by Charge Type

​Filter by Usage Unit

​Filter by Tag

​Filter by Single Tag

​Filter for Multiple Values from a Single Tag Key

​Filter by Multiple Tags

​Filter for Matching Tags Using LIKE

​Filter for Tags Using Flexible Matching

​Filter for Untagged Resources

​Troubleshooting

Cost Reports VQL Schema

Keywords

Syntax

VQL Examples

Filter Across All Providers

Combining Providers

Cost Allocation

Costs from a List of Regions

Get Marketplace Transactions

Costs by Account ID

Costs by Provider Account ID

Per-Resource Costs and Costs by Service

Multiple Resource IDs

Costs by Specific Category

Costs by Specific Subcategory

Cost by Charge Type

Filter by Usage Unit

Filter by Tag

Filter by Single Tag

Filter for Multiple Values from a Single Tag Key

Filter by Multiple Tags

Filter for Matching Tags Using `LIKE`

Filter for Tags Using Flexible Matching

Filter for Untagged Resources

Troubleshooting