Filter Object Definition V2

The Filter Object is the standard structure for refining data in Finout API V2. It is used in two contexts:

  • Cost and Usage API V2 — to scope query results to specific dimensions, providers, or tag values.

  • Virtual Tag rules for Virtual Tags API V2 (coming soon) — to define the conditions that assign records to a specific tag value (e.g., "Team A" or "Project X"), with an optional default value for records that match no rule.

The same filter structure applies in both contexts.


Filter structure

Filters support two levels of complexity.

Simple condition (no logical operator)

Use a direct condition object when you have a single filter requirement.

{
  "filters": {
    "costCenter": "AWS",
    "key": "aws_account_name",
    "type": "tag",
    "displayName": "Account Name",
    "operator": "oneOf",
    "value": ["004a533177", "0371d7d3bf"]
  }
}

Complex conditions (nested logical operators)

Use AND and OR keys to group multiple conditions. You can nest them to any depth for complex logic.


Filter object fields

Field
Type
Required
Description
Example

costCenter

string

Yes

The cost center associated with the filter.

"AWS", "GCP", "Kubernetes", "Snowflake", "Datadog", "Azure", "Custom Cost"

key

string

Yes

The field identifier to filter on. Retrieve valid keys from Query Language API V2 /keys.

"deployment"

type

string

Yes

The key type. Use virtual_tag when filtering on Virtual Tags. Retrieve valid types from Query Language API V2 /keys.

"billing_dimension", "virtual_tag"

operator

string

Yes

The comparison operator to apply. See Supported operators below.

"oneOf"

value

array

Conditional

The values to match against. Not required for exists and notExists operators.

["us-east-1", "us-east-2"]

displayName

string

No

The human-readable label for the field as shown in Finout. Optional and informational only.

"Account Name"


Supported operators

Operator

Requires value

Description

oneOf

Yes

Matches if the field value equals any value in the array.

notOneOf

Yes

Matches if the field value does not equal any value in the array.

is

Yes

Matches if the field value is exactly equal to the specified value.

notIs

Yes

Matches if the field value is not equal to the specified value.

contains

Yes

Matches if the field value contains the specified substring.

notContains

Yes

Matches if the field value does not contain the specified substring.

exists

No

Matches if the field value exists (is not null or empty).

notExists

No

Matches if the field value does not exist (is null or empty).


Supported types

Retrieve the exact type values for your keys from the Query Language API V2 /keys endpoint.


Examples

Example 1 — Three-rule Virtual Tag configuration

This example shows a Virtual Tag with three rules. Records are evaluated against each rule in order. The first rule that matches determines the tag value assigned to the record. If no rule matches, the record receives the defaultValue.

How this rule set works:

The first rule assigns records to "Finout" when all three conditions match (AND logic):

  • AWS aws_account_name billing dimension equals Finout

  • AWS f_operation billing dimension equals AAAA

  • Datadog service billing dimension equals Abra

The second rule assigns records to "Finout-Subaccount" when a single condition matches:

  • AWS aws_account_name tag equals Finout-Subaccount

The third rule assigns records to "AWS" when a single condition matches:

  • Global cost_center_type billing dimension equals AWS

Records that match none of the rules receive the default value "Untagged".


Example 2 — Nested AND / OR logic

This example shows two rules using nested AND and OR operators. The first rule uses the logic: (condition 1 OR condition 2) AND condition 3.

How this rule set works:

The first rule assigns records to "Tag1" when the following combined condition matches:

  • (Azure accountownerid tag is one of ServiceA, ServiceB, or ServiceC OR Global cost_center_type is one of AccountX or AccountY) AND

  • GCP department tag is one of ServiceA or ServiceB

The second rule assigns records to "Tag2" when a single condition matches:

  • AWS s3_bucket resource value is one of AccountZ or AccountW

Records that match neither rule receive the default value "DefaultTag".

Last updated

Was this helpful?