# Virtual Tags API V1 The Virtual Tags API allows you to create, retrieve, update, and delete Virtual Tag configurations. [Virtual Tags](/user-guide/inform/virtual-tags.md) 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 ](/api/finout-api/generate-an-api-token.md)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](/api/finout-api/generate-an-api-token.md) 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](/api/finout-api/generate-an-api-token.md) 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](/api/finout-api/generate-an-api-token.md) 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](/api/finout-api/generate-an-api-token.md) 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](/api/finout-api/filter-object-definition-v1.md) 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](/api/finout-api/filter-object-definition-v1.md) 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.finout.io/api/finout-api/virtual-tags-api-v1.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.