# Virtual Tags API The Virtual Tags API allows you to create, retrieve, update, and delete Virtual Tag configurations. [Virtual Tags](https://docs.finout.io/user-guide/inform/virtual-tags) organize and categorize data based on custom rules and filters. {% hint style="info" %} **Note**: Reallocation is currently unsupported in the Virtual Tag API. {% endhint %} ## `GET``/Virtual Tags` Retrieves all virtual tag configurations. {% hint style="success" %} **Prerequisites** * [Generate a Client ID and Secret Key ](https://docs.finout.io/api/finout-api/generate-an-api-token)from Finout to add in Headers. {% endhint %} **Request**\\ \ `https://app.finout.io/v1/virtual-tags` **Response** {% tabs %} {% tab title="Query Response" %} ```json { "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": "eric.brown@finout.io", "updatedBy": "zak.brown@finout.io", "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": "zak.brown@finout.io", "updatedBy": "zak.brown@finout.io", "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": "zak.brown@finout.io", "id": "652a12f9-2313-45a2-ba7a-3c751943a53c", "defaultValue": "Internal Spend" } ] } ``` {% endtab %} {% tab title="Common Errors" %} 400 - Bad Request 401 - Unauthorized 403 - Forbidden 404- Not Found 429 - Too Many Request 500 - Internal Server Error {% endtab %} {% tab title="422" %} Unprocessable Request {% endtab %} {% endtabs %} ## `POST` `/Virtual Tag` Create a new virtual tag. {% hint style="success" %} **Prerequisites** * [Generate a Client ID and Secret Key](https://docs.finout.io/api/finout-api/generate-an-api-token) from Finout to add in Headers. {% endhint %} **Request** `https://app.finout.io/v1/virtual-tags` {% tabs %} {% tab title="Custom Query Request" %} ```json { "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" } ``` {% endtab %} {% tab title="Request with Megabill Key" %} ```json { "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" } } ``` {% endtab %} {% endtabs %} *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.](#h_1c54feda7a) | | 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** {% tabs %} {% tab title="Custom Query Response" %} ```json { "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" } ``` {% endtab %} {% tab title="Response with Megabill Key" %} ```json { "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" } } ``` {% endtab %} {% endtabs %} ## `PUT``/Virtual Tags` Update a current virtual tag. {% hint style="success" %} **Prerequisites** * [Generate a Client ID and Secret Key](https://docs.finout.io/api/finout-api/generate-an-api-token) from Finout to add in Headers. * Get a virtual tag ID. {% endhint %} **Request** `https://app.finout.io/v1/virtual-tags/{id}` *Path parameter* | Parameter | Type | Description | | --------- | ------ | ------------------------------------------- | | ID | String | The ID of the Virtual Tag is to be updated. | {% tabs %} {% tab title="Custom Request Query" %} ```json { "name": "Demo Feature cost2223", "rules": [ { "to": "Fea", "filters": { "costCenter": "AWS", "key": "type", "displayName": "Instance Type", "operator": "oneOf", "value": [ "NEW1", "NEW2", "NEW3" ] } } ], "defaultValue": { } ``` {% endtab %} {% tab title="Request with Megabill Key" %} ```postman_json { "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" } } ``` {% endtab %} {% endtabs %} *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](#h_1c54feda7a). | | 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** {% tabs %} {% tab title="Custom Query Response" %} ```json { "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" } ``` {% endtab %} {% tab title="Response with Megabill Key" %} ```json { "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" } ``` {% endtab %} {% endtabs %} ## `GET``/Virtual Tag By ID` Retrieves the specified Virtual Tag configuration. {% hint style="success" %} **Prerequisites** * [Generate a Client ID and Secret Key](https://docs.finout.io/api/finout-api/generate-an-api-token) from Finout to add in Headers. * Get a virtual tag ID. {% endhint %} **Request** `https://app.finout.io/v1/virtual-tags/{id}` *Path Parameter* | Parameter | Type | Description | | --------- | ------ | -------------------------------------- | | id | String | The id of the Virtual Tag to retrieve. | **Response** {% tabs %} {% tab title="200" %} ```json { "requestId": "168b62f4-92f7-4871-aaf9-04ce725fc303", "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259", "createdBy": "elisha.saidoff@finout.io", "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": "elisha.saidoff@finout.io", "id": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89", "defaultValue": "Untagged" } ``` {% endtab %} {% endtabs %} ## `DELETE``/Virtual Tag` Deletes the specified Virtual Tag. {% hint style="success" %} **Prerequisites** * [Generate a Client ID and Secret Key](https://docs.finout.io/api/finout-api/generate-an-api-token) from Finout to add in Headers. * Get a virtual tag ID. {% endhint %} **Request** `https://app.finout.io/v1/virtual-tags/{id}` *Path parameter* | Parameter | Type | Description | | --------- | ------ | ------------------------------------ | | id | 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](https://docs.finout.io/api/finout-api/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)" | | id | string | The unique identifier of the Virtual Tag. | "b11c9be2-b7a0-4209-a00e-44ac2ccce0f7" | **“Rules” object definition** | Field | Type | Description | Example Value | | -------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | to |

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](https://docs.finout.io/api/finout-api/filter-object-definition) for more information. | | timeframe (optional) | object | Enables you to apply virtual tag rules within defined date ranges. |

"timeframe": {

"from": \,

"to": \

}

or for open ended timeframe:

"timeframe": {

"from": \

}

| ## 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 | | Is | 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.