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.

{
  "filters": {
    "AND": [
      {
        "costCenter": "AWS",
        "key": "region",
        "type": "billing_dimension",
        "displayName": "Regions",
        "operator": "oneOf",
        "value": ["us-east-1", "us-east-2", "eu-central-1"]
      },
      {
        "costCenter": "Global",
        "key": "cost_center_type",
        "type": "billing_dimension",
        "displayName": "Cost Center",
        "operator": "oneOf",
        "value": ["AWS"]
      }
    ]
  }
}

---

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.

{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Test",
  "rules": [
    {
      "to": "Finout",
      "filters": {
        "AND": [
          {
            "costCenter": "AWS",
            "key": "aws_account_name",
            "type": "billing_dimension",
            "displayName": "Account Name",
            "operator": "oneOf",
            "value": ["Finout"]
          },
          {
            "costCenter": "AWS",
            "key": "f_operation",
            "type": "billing_dimension",
            "displayName": "API Operation",
            "operator": "oneOf",
            "value": ["AAAA"]
          },
          {
            "costCenter": "Datadog",
            "key": "service",
            "type": "billing_dimension",
            "displayName": "Cost per Customer",
            "operator": "oneOf",
            "value": ["Abra"]
          }
        ]
      }
    },
    {
      "to": "Finout-Subaccount",
      "filters": {
        "costCenter": "AWS",
        "key": "aws_account_name",
        "type": "tag",
        "displayName": "Account Name",
        "operator": "oneOf",
        "value": ["Finout-Subaccount"]
      }
    },
    {
      "to": "AWS",
      "filters": {
        "costCenter": "Global",
        "key": "cost_center_type",
        "type": "billing_dimension",
        "displayName": "Cost Center",
        "operator": "oneOf",
        "value": ["AWS"]
      }
    }
  ],
  "category": "Project",
  "createdBy": "User",
  "updatedBy": "User",
  "createdAt": "Wed Mar 13 2024 15:40:46 GMT+0000 (Greenwich Mean Time)",
  "updatedAt": "Thu Mar 21 2024 10:49:17 GMT+0000 (Greenwich Mean Time)",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "defaultValue": "Untagged"
}

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.

{
  "requestId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "exampleName",
  "rules": [
    {
      "to": "Tag1",
      "filters": {
        "AND": [
          {
            "OR": [
              {
                "costCenter": "Azure",
                "key": "accountownerid",
                "type": "tag",
                "displayName": "Account Owner Id",
                "operator": "oneOf",
                "value": ["ServiceA", "ServiceB", "ServiceC"]
              },
              {
                "costCenter": "Global",
                "key": "cost_center_type",
                "type": "billing_dimension",
                "displayName": "Cost Center",
                "operator": "oneOf",
                "value": ["AccountX", "AccountY"]
              }
            ]
          },
          {
            "costCenter": "GCP",
            "key": "department",
            "type": "tag",
            "displayName": "Service Name",
            "operator": "oneOf",
            "value": ["ServiceA", "ServiceB"]
          }
        ]
      }
    },
    {
      "to": "Tag2",
      "filters": {
        "costCenter": "AWS",
        "key": "s3_bucket",
        "type": "resource",
        "displayName": "Account Name",
        "operator": "oneOf",
        "value": ["AccountZ", "AccountW"]
      }
    }
  ],
  "createdBy": "CreatorName",
  "updatedBy": "UpdaterName",
  "createdAt": "Date and Time",
  "updatedAt": "Date and Time",
  "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "defaultValue": "DefaultTag"
}

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".