Virtual Tags API

The Virtual Tags API allows you to create, retrieve, update, and delete Virtual Tag configurations. Virtual Tags organize and categorize data based on custom rules and filters.

Note: Reallocation is currently unsupported in the Virtual Tag API.

`GET/Virtual Tags`

Retrieves all virtual tag configurations.

Prerequisites

Generate a Client ID and Secret Key from Finout to add in Headers.

Request https://app.finout.io/v1/virtual-tags

Response

{
  "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
  "requestId": "6e0f327e-9948-440b-b577-d0203aa374e9",
  "virtualTags": [
    {
      "id": "2e29ad96-3616-43d7-9858-a00477457e6a",
      "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
      "name": "Demo Feature cost",
      "defaultValue": "unallocated",
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdAt": "Mon Sep 09 2024 21:47:55 GMT+0000 (Greenwich Mean Time)",
      "updatedAt": "Wed Aug 13 2025 17:55:07 GMT+0000 (Greenwich Mean Time)",
      "rules": [
        {
          "to": "Shared IT",
          "filters": {
            "OR": [
              {
                "costCenter": "Global",
                "key": "cost_center_type",
                "displayName": "Cost Center",
                "operator": "oneOf",
                "value": [
                  "Azure",
                  "databricks",
                  "Datadog",
                  "GCP",
                  "kubernetes",
                  "snowflake"
                ]
              },
              {
                "costCenter": "Global",
                "key": "cost_center_type",
                "displayName": "Cost Center",
                "operator": "contains",
                "value": "Custom"
              }
            ]
            },
               "timeframe": {
                 "from": 1756166400000,
                 "to": 1756166400100
          }
        }
      ]
    },
    {
      "id": "4f816fc1-6b3a-4902-b6b5-9759ba5ca83c",
      "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
      "name": "SNOW/Chase/Customer Chargeback",
      "defaultValue": "unallocated",
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]",
      "createdAt": "Tue Oct 17 2023 18:08:17 GMT+0000 (Greenwich Mean Time)",
      "updatedAt": "Fri Aug 16 2024 18:00:49 GMT+0000 (Greenwich Mean Time)",
      "rules": [
        {
          "to": {
            "key": "cc36dc5e-68b8-4f3d-b811-e24a7876b636",
            "costCenter": "Virtual Tags"
          },
          "filters": {
            "costCenter": "Virtual Tags",
            "key": "cc36dc5e-68b8-4f3d-b811-e24a7876b636",
            "displayName": "Customer",
            "operator": "notOneOf",
            "value": [
              "Shared Platform"
            ]
          }
        }
      ]
    },
    {
      "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
      "name": "GO/Divisions",
      "rules": [
        {
          "to": "California AW",
          "filters": {
            "OR": [
              {
                "costCenter": "AWS",
                "key": "aws_account_name",
                "displayName": "Account Name",
                "operator": "is",
                "value": "cc25606f77"
              },
              {
                "costCenter": "Datadog",
                "key": "organization",
                "displayName": "Organization",
                "operator": "is",
                "value": "laminated-service"
              },
              {
                "costCenter": "Kubernetes",
                "key": "k8s_cluster",
                "displayName": "k8s_cluster",
                "operator": "oneOf",
                "value": [
                  "aged-shepherd",
                  "each-bulwark",
                  "mad-band",
                  "mild-cleat"
                ]
              }
            ]
          }
        },
        {
          "to": "Shared",
          "filters": {
            "costCenter": "Virtual Tags",
            "key": "cc36dc5e-68b8-4f3d-b811-e24a7876b636",
            "displayName": "Customer",
            "operator": "oneOf",
            "value": [
              "Shared Platform"
            ]
          }
        }
      ],
      "createdAt": "Tue Aug 12 2025 15:29:51 GMT+0000 (Greenwich Mean Time)",
      "updatedAt": "Tue Aug 12 2025 15:29:51 GMT+0000 (Greenwich Mean Time)",
      "updatedBy": "[email protected]",
      "id": "652a12f9-2313-45a2-ba7a-3c751943a53c",
      "defaultValue": "Internal Spend"
    }
  ]
}

`POST` `/Virtual Tag`

Create a new virtual tag.

Prerequisites

Generate a Client ID and Secret Key from Finout to add in Headers.

Request

https://app.finout.io/v1/virtual-tags

{
  "name": "Demo Feature cost2222",
  "rules": [
    {
      "to": "Fea",
      "filters": {
        "costCenter": "AWS",
        "key": "type",
        "displayName": "Instance Type",
        "operator": "oneOf",
        "value": [
          "a1.2xlarge",
          "a1.large",
          "a1.medium"
        ]
      }
    }
  ],
  "defaultValue": "Untagged"
}

{
  "name": "DocDemo",
  "rules": [
    {
      "to": {
        "costCenter": "AWS",
        "key": "f_inst_type"
      },
      "filters": {
        "costCenter": "AWS",
        "key": "usage_account_id",
        "operator": "oneOf",
        "value": ["a1.2xlarge", "a1.large", "a1.medium"]
      }
    }
  ],
  "defaultValue": {
        "key": "eks_cluster_name",
        "costCenter": "AWS"
    }
}

Body parameters

Parameter

Type

Description

name

string

The name of the virtual tag.

rules

array

An array of rules defines the filters and conditions for the virtual tag. See Virtual Tag Objects.

defaultValue

Custom Value -string Megabill key - object

An object defining the default value for the Virtual Tag.

isCaseSensitive

boolean

The isCaseSensitive flag is set to false by default. When explicitly set to true, the API preserves the exact casing of the costCenter and key fields (inside rules).

Response

{
    "requestId": "5f8ae41e-02fb-4a03-900e-7451dc3d073f",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "Finout",
    "name": "Demo Feature cost2223",
    "archiverIgnore": false,
    "rules": [
        {
            "to": "Fea",
            "filters": {
                "costCenter": "AWS",
                "key": "type",
                "displayName": "Instance Type",
                "operator": "oneOf",
                "value": [
                    "a1.2xlarge",
                    "a1.large",
                    "a1.medium"
                ]
            }
        }
    ],
    "createdAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "id": "d1a99df2-dfb3-4da6-8877-91a655d5deb8",
    "defaultValue": "Untagged"
}

{
    "requestId": "75edac79-3e45-43a6-aebb-28547fe877b3",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "Finout",
    "name": "DocDemo",
    "type": "default",
    "archiverIgnore": false,
    "rules": [
        {
            "to": {
                "key": "cloud_service",
                "costCenter": "AWS"
            },
            "filters": {
                "costCenter": "AWS",
                "key": "type",
                "displayName": "Instance Type",
                "operator": "oneOf",
                "value": [
                    "a1.2xlarge",
                    "a1.large",
                    "a1.medium"
                ]
            }
        }
    ],
    "createdAt": "Tue Sep 09 2025 07:54:19 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Tue Sep 09 2025 07:54:19 GMT+0000 (Greenwich Mean Time)",
    "updatedBy": "Finout",
    "id": "16d71c91-de3c-46d8-a472-c9b09e1419b6",
    "defaultValue": {
        "key": "eks_cluster_name",
        "costCenter": "AWS"
    }
}

`PUT/Virtual Tags`

Update a current virtual tag.

Prerequisites

Generate a Client ID and Secret Key from Finout to add in Headers.
Get a virtual tag ID.

Request

https://app.finout.io/v1/virtual-tags/{id}

Path parameter

Parameter

Type

Description

String

The ID of the Virtual Tag is to be updated.

{
  "name": "Demo Feature cost2223",
  "rules": [
    {
      "to": "Fea",
      "filters": {
        "costCenter": "AWS",
        "key": "type",
        "displayName": "Instance Type",
        "operator": "oneOf",
        "value": [
          "NEW1",
          "NEW2",
          "NEW3"
        ]
      }
    }
  ],
  "defaultValue": {
}

{
  "name": "DocDemo2",
  "rules": [
    {
      "to": {
        "costCenter": "AWS",
        "key": "cloud_service"
      },
      "filters": {
        "costCenter": "AWS",
        "key": "type",
        "operator": "is",
        "value": "NEW1"
      }
    }
  ],
  "defaultValue": {
        "key": "eks_cluster_name",
        "costCenter": "AWS"
    }
}

Request Body Parameters

Parameter

Type

Description

name

string

The name of the Virtual Tag.

rules

array

An array of rules defines the filters and conditions for the virtual tag. See Virtual Tag Objects.

defaultValue

Custom Value -string Megabill key - object

An object defining the default value for the Virtual Tag.

isCaseSensitive

boolean

The isCaseSensitive flag is set to false by default. When explicitly set to true, the API preserves the exact casing of the costCenter and key fields (inside rules).

Response

{
    "requestId": "c17dc36d-6007-48f6-a06f-35ccb74f58a8",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "Finout",
    "name": "Demo Feature cost2223",
    "archiverIgnore": false,
    "rules": [
        {
            "to": "Fea",
            "filters": {
                "costCenter": "AWS",
                "key": "type",
                "displayName": "Instance Type",
                "operator": "oneOf",
                "value": [
                    "NEW1",
                    "NEW2",
                    "NEW3"
                ]
            }
        }
    ],
    "createdAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Mon Nov 18 2024 08:33:52 GMT+0000 (Greenwich Mean Time)",
    "updatedBy": "Finout",
    "id": "d1a99df2-dfb3-4da6-8877-91a655d5deb8",
    "defaultValue": "Untagged"
}

{
    "requestId": "aafc0271-0337-4421-b56f-9cbc06f54aef",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "Finout",
    "name": "DocDemo2",
    "type": "default",
    "archiverIgnore": false,
    "rules": [
        {
            "to": {
                "key": "cloud_service",
                "costCenter": "AWS"
            },
            "filters": {
                "costCenter": "AWS",
                "key": "type",
                "displayName": "Instance Type",
                "operator": "is",
                "value": "NEW1"
            }
        }
    ],
    "createdAt": "Tue Sep 09 2025 08:14:05 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Tue Sep 09 2025 08:19:52 GMT+0000 (Greenwich Mean Time)",
    "updatedBy": "Finout",
    "id": "424a20a9-7187-447d-9d55-e4fc7d022eb9",
    "defaultValue": "Untagged"
}

`GET/Virtual Tag By ID`

Retrieves the specified Virtual Tag configuration.

Prerequisites

Generate a Client ID and Secret Key from Finout to add in Headers.
Get a virtual tag ID.

Request

https://app.finout.io/v1/virtual-tags/{id}

Path Parameter

Parameter

Type

Description

String

The id of the Virtual Tag to retrieve.

Response

{
    "requestId": "168b62f4-92f7-4871-aaf9-04ce725fc303",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "[email protected]",
    "name": "Demo Feature cost",
    "rules": [
        {
            "to": "demo",
            "filters": {
                "costCenter": "AWS",
                "key": "f_inst_type",
                "displayName": "Instance Type",
                "operator": "oneOf",
                "value": [
                    "a1.2xlarge",
                    "a1.large",
                    "a1.medium"
                ]
            }
        }
    ],
    "createdAt": "Sun Sep 29 2024 08:20:37 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Tue Oct 29 2024 12:13:50 GMT+0000 (Greenwich Mean Time)",
    "updatedBy": "[email protected]",
    "id": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89",
    "defaultValue": "Untagged"
}

`DELETE/Virtual Tag`

Deletes the specified Virtual Tag.

Prerequisites

Generate a Client ID and Secret Key from Finout to add in Headers.
Get a virtual tag ID.

Request

https://app.finout.io/v1/virtual-tags/{id}

Path parameter

Parameter

Type

Description

string

The id of the Virtual Tag to delete.

Response

The Virtual tag is deleted.

Virtual Tags Objects

The Virtual Tags object represents a configuration used for resource allocation and filtering. It contains the following fields:

Field

Type

Description

Example Value

accountId

string

The unique identifier of the account is associated with the Virtual Tag.

"e12498cc-594a-4740-94a5-8324e7399bb2"

name

string

The name of the Virtual Tag.

"nir test"

rules

array

An array of RULE objects that defines the filtering criteria for the Virtual Tag.

See Filter Object Definition for more information.

createdBy

string

The name of the user who created the Virtual Tag.

"Nir"

updatedBy

string

The name of the user who last updated the Virtual Tag.

"Asaf Liveanu"

defaultValue

Custom Value -string Megabill key - object

An object defining the default value for the Virtual Tag.

“untagged” or "defaultValue": { "key": "eks_cluster_name", "costCenter": "AWS" }

createdAt

string

The date and time when the Virtual Tag was created.

"Tue May 16 2023 13:15:53 GMT+0000 (Greenwich Mean Time)"

updatedAt

string

The date and time when the Virtual Tag was last updated.

"Sat Jun 10 2023 16:06:25 GMT+0000 (Greenwich Mean Time)"

string

The unique identifier of the Virtual Tag.

"b11c9be2-b7a0-4209-a00e-44ac2ccce0f7"

“Rules” object definition

Field

Type

Description

Example Value

Custom Value -string Megabill key - object

The destination or target for the filtered data.

"Data Team" or "defaultValue": { "key": "eks_cluster_name", "costCenter": "AWS" }

filters

object

An object containing the filter conditions for the rule.

See Filter Object Definition for more information.

timeframe (optional)

object

Enables you to apply virtual tag rules within defined date ranges.

"timeframe": {

"from": <timestamp>,

"to": <timestamp>

} or for open ended timeframe: "timeframe": {

"from": <timestamp>

}

Supported Filters Operators

The following is a list of supported operators and the data types each one is compatible with:

Operators

Values structure

Oneof

array

string

Exists

null

Contains

string

Not oneof

array

Is not

string

Not contains

string

Not exists

null

Error Handling

The API returns standard HTTP error codes to indicate the success or failure of a request. The following common HTTP errors may be returned:

400 Bad Request: The request is malformed or missing the required parameters. Check the request structure carefully for syntax typos and resubmit the request.
401 Unauthorized: The request lacks valid authentication credentials. Ensure that you have added your credentials to the request header and resubmit your request. If this still doesn't work, contact Finout Support.
403 Forbidden: The request is understood, but the server refuses to fulfill it due to access restrictions. Contact Finout Support.
404 Not Found: The requested resource is not found. Resubmit the request with a valid resource ID.
429 Too Many Requests: The user has sent too many requests in a given period.
422 Unprocessable Request: Check the virtual tag composition and structures.
500 Internal Server Error: An unexpected error occurred on the server.

PreviousQuery Language API NextCostGuard API

Last updated 1 month ago

Was this helpful?

hashtagGET/Virtual Tags

hashtagPOST /Virtual Tag

hashtagPUT/Virtual Tags

hashtagGET/Virtual Tag By ID

hashtagDELETE/Virtual Tag

hashtagVirtual Tags Objects

hashtagSupported Filters Operators

hashtagError Handling

`GET/Virtual Tags`

`POST` `/Virtual Tag`

`PUT/Virtual Tags`

`GET/Virtual Tag By ID`

`DELETE/Virtual Tag`

Virtual Tags Objects

Supported Filters Operators

Error Handling