Introduction

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.

The Finout API is fully secured using your secret key and client token, which can be managed from your Finout account. Your Finout account allows for five concurrent requests per API key.

For instructions on configuring an API key, please refer to the main documentation on this topic here.

Note: The Reallocation and MegaBill Key segmentation are currently unsupported in the Virtual Tag API.

Configure API Access

When you generate the API token, it creates both a secret key and a client ID (token).

Important: Please copy your Client ID and Secret Key and keep this in a safe place. The Secret Key only appears once and will not be shown again!

These parameters will be passed in the authorization header when you invoke any of the Finout API methods.

To configure API access:

Select Admin Portal (from the user dropdown)
Select API Tokens
Click Generate Token
Enter a Description
Click Create
Copy the Client ID and Secret Key. Note: You must do this at this stage, as you will not be able to copy it later!
Click Done

How do you use the Client ID and Secret Key?

Pass the following as header parameters when invoking any of the Finout endpoints:

x-finout-client-id
x-finout-secret-key

Virtual Tags Object

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 the table below.
category	string	The category of the Virtual Tag.	"Project"
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	string	An object defining the default value for the Virtual Tag.	“untagged”
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	string	The destination or target for the filtered data.	"Data Team"
filters	object	An object containing the filter conditions for the rule.	See the table below.

“Filter” object definition

In the Finout Virtual Tags API documentation, the structure of the filters object can be explained by starting with simpler usage and then detailing more complex scenarios:

Simple Conditions Without Logical Operators:

Use direct condition keys for single-condition requirements.

Example JSON:

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

Complex Conditions with Nested Logical Operators:

AND and OR keys represent logical operators for grouping multiple conditions.

You can nest multiple layers of AND and OR for intricate conditional logic.

Example JSON:

{
  "filters": {
    "AND": [
      {
        "OR": [
          {
            "costCenter": "AWS",
            "key": "condition1",
            "operator": "equals",
            "value": "value1"
          },
          {
            "costCenter": "AWS",
            "key": "condition2",
            "operator": "equals",
            "value": "value2"
          }
        ]
      },
      {
        "costCenter": "AWS",
        "key": "condition3",
        "operator": "equals",
        "value": "value3"
      }
    ]
  }
}

Filter operator object definition

Field	Type	Description	Example Value
costCenter	string	The cost center associated with the filter.	"AWS" , "GCP", "Kubernetes" , "Snowflake" , "Virtual Tags" , "Datadog" , "Azure" , "Custom Cost"
operator	string	The comparison operator to apply for the filter (e.g., "oneOf", "equal", "greaterThan").	"oneOf"
value	array	An array of values to use the operator against.	["Amazon Web Services EMEA KFIR"]
key	string	The key in Finout filters. For non-unique keys or specific keys (finrichment), a transform function is applied as follows: finrichment is returned as f_ plus the Kubernetes key and the node/pod label is returned as nl_<key>/pl_<key>	“1233442423423” “finrichment_usage_type” -> “f_usage_type” Use Finout’s Query Language API to get a list of the available keys.

Note: "displayName" is retrieved in the GET API call. This parameter should not be sent in the POST/PUT API calls.

Supported Operators

The following operators can be used in the rule definitions to specify filtering conditions:

oneOf: Matches the resource value if it is equal to any of the specified values.
notOneOf: Matches the resource value if it is not equal to any of the specified values.
is: Matches the resource value if it is exactly equal to the specified value.
isNot: Matches the resource value if it is not equal to the specified value.
contains: Matches the resource value if it contains the specified substring.
notContains: Matches the resource value if it does not contain the specified substring.
exists: Matches the resource value if it exists (not null or empty).
notExists: Matches the resource value if it does not exist (null or empty).

Example rule configuration

{
"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",
"displayName": "Account Name",
"operator": "oneOf",
"value": [
"Finout"
]
},
{
"costCenter": "AWS",
"key": "f_operation",
"displayName": "API Operation",
"operator": "oneOf",
"value": [
"AAAA"
]
},
{
"costCenter": "Virtual Tags",
"key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"displayName": "Cost per Customer",
"operator": "oneOf",
"value": [
"Abra"
]
}
]
}
},
{
"to": "Finout-Subaccount",
"filters": {
"costCenter": "AWS",
"key": "aws_account_name",
"displayName": "Account Name",
"operator": "oneOf",
"value": [
"Finout-Subaccount"
]
}
},
{
"to": "AWS",
"filters": {
"costCenter": "Global",
"key": "cost_center_type",
"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"

In the example above, the rule engine is configured with two rules. The first rule filters resources with costCenter equal to "virtualTag" and type equal to "virtual_tag" using the oneOf operator, matching the values "Aged", "AllArid", "BidBare", "Calm", or "Coal". The matching resources are then directed to the "Application" destination.

The second rule filters resources with costCenter equal to "virtualTag" and type equal to "virtual_tag" using the contains operator, matching the value "Jet". The matching resources are directed to the "Backend" destination.

Example rules and filter conditions

{
  "requestId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "exampleName",
  "rules": [
    {
      "to": "Tag1",
      "filters": {
        "AND": [
          {
            "OR": [
              {
                "costCenter": "Center1",
                "key": "service_key",
                "displayName": "Service Name",
                "operator": "oneOf",
                "value": [
                  "ServiceA",
                  "ServiceB",
                  "ServiceC"
                ]
              },
              {
                "costCenter": "Center1",
                "key": "account_name_key",
                "displayName": "Account Name",
                "operator": "oneOf",
                "value": [
                  "AccountX",
                  "AccountY"
                ]
              }
            ]
          },
          {
            "costCenter": "Center1",
            "key": "service_key",
            "displayName": "Service Name",
            "operator": "oneOf",
            "value": [
              "ServiceA",
              "ServiceB"
            ]
          }
        ]
      }
    },
    {
      "to": "Tag2",
      "filters": {
        "costCenter": "Center2",
        "key": "account_name_key",
        "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"
}

In the provided example, the third rule illustrates complex conditional logic using both "AND" and "OR" operators. This rule's filter conditions demonstrate the logic: "(condition 1 AND condition 2) OR (condition 1 AND condition 3)". This showcases how multiple conditions can be intricately grouped within "AND" or "OR" relationships, allowing for the creation of sophisticated filtering logic for virtual tags. This example serves to show the versatility and depth of the filtering system in handling diverse and complex tagging scenarios.

API Endpoints

Route: https://app.finout.io/v1/

Method	Endpoint	Feature
GET	/virtual-tags	Retrieve all Virtual Tag configurations.
POST	/virtual-tags	Create a new Virtual Tag.
PUT	Virtual-tags/{id}	Update the configuration of an existing Virtual Tag.
GET	/virtual-tags/{id}	Retrieve the Virtual Tag configuration for a specific Virtual Tag.
DELETE	/virtual-tags/{id}	Delete a Virtual Tag configuration.

Retrieve all Virtual Tags

Retrieves all virtual tag configurations.

Syntax

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

Body parameters

None

Returns

Code

Description

200

All virtual tags.

{
  "accountId": "12345",
  "requestId": "{request_id}",
  "virtualTags": [
    {
      "id": "c7c82bba-0f77-48c4-bb0b-da60bc1bff2b",
      "name": "Dev Group",
      "rules": [
        {
          "to": "Application",
          "filters": {
            "costCenter": "virtualTag",
            "operator": "oneOf",
            "value": [
              "Aged",
              "AllArid",
              "BidBare",
              "Calm",
              "Coal"
            ]
          }
        },
        {
          "to": "Backend",
          "filters": {
            "costCenter": "virtualTag",
            ,
            "operator": "oneOf",
            "value": [
              "EachEasy",
              "Free",
              "Jet",
              "Lime",
              "Cold"
            ]
          }
        }
      ],
      "category": "Project",
      "createdBy": "Tom Zohar",
      "updatedBy": "Asaf Liveanu",
      "defaultValue": "Untagged",
      "endpoints": [
        
      ],
      "createdAt": "Sun Mar 05 2023 15:08:21 GMT+0000 (Greenwich Mean Time)",
      "updatedAt": "Tue May 30 2023 04:29:34 GMT+0000 (Greenwich Mean Time)"
    }
  ]
}

…

Create a New Virtual Tag

To learn how to create a Virtual Tag, please refer to our main documentation.

Syntax

POST/v1/virtual-tags/{id}

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	string	The defaultValue object.

Example

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

Returns

Code

Description

201

Created{
  "name": "Dev Group",
  "rules": [
    {
      "to": "Application",
      "filters": {
        "costCenter": "virtualTag",
        "operator": "oneOf",
        "value": [
          "Aged",
          "AllArid",
          "BidBare",
          "Calm",
          "Coal"
        ],
        "key": "4af55967-96e0-4827-833b-7999e7ce66f5",
        "name": "yosi"
      }
    }
  ],
  "category": "Project",
  "createdBy": "Tom Zohar",
  "updatedBy": "Asaf Liveanu",
  "defaultValue": "Untagged",
  "createdAt": "Sun Mar 05 2023 15:08:21 GMT+0000 (Greenwich Mean Time)",
  "updatedAt": "Tue May 30 2023 04:29:34 GMT+0000 (Greenwich Mean Time)",
  "id": "c7c82bba-0f77-48c4-bb0b-da60bc1bff2b"
}

Update Virtual Tag configuration

Syntax

PUT/v1/virtual-tags/{id}

Path parameter

Parameter	Type	Description
ID	String	The ID of the Virtual Tag is to be updated.

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	string	The defaultValue object.

Example

{
  "name": "Dev Group",
  "rules": [
    {
      "to": "Application",
      "filters": {
        "costCenter": "virtualTag",
        "operator": "oneOf",
        "value": [
          "NewValue1",
          "NewValue2",
          "NewValue3"
        ],
      }
    },
    ...
  ],
  "defaultValue": "Untagged"
}

Returns

Code

Description

200

OK{
  "name": "Dev Group",
  "rules": [
    {
      "to": "Application",
      "filters": {
        "costCenter": "virtualTag",
        "operator": "oneOf",
        "value": [
          "NewValue1",
          "NewValue2",
          "NewValue3"
        ],
        "path": "Virtual Tags/4af55967-96e0-4827-833b-7999e7ce66f5",
        "key": "4af55967-96e0-4827-833b-7999e7ce66f5"
      }
    },
    ...
  ],
  "defaultValuedefault": "Untagged"
}

Retrieve Virtual Tag by ID

Retrieves the specified Virtual Tag configuration.

Syntax

GET/v1/virtual-tags/{id}

Path Parameter

Parameter	Type	Description
id	String	The id of the Virtual Tag to retrieve.

Body Parameters

None

Delete a Virtual Tag

Deletes the specified Virtual Tag.

Syntax

DELETE/v1/virtual-tags/{id}

Path parameter

Parameter	Type	Description
id	string	The id of the Virtual Tag to delete.

Body parameters

None

Returns

Code	Description
200	OK
…
204	No Content

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:

HTTP error codes

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.

Example

{
  "requestId": "{request_id}",
  "message": "Unprocessable Entity: Invalid JSON configuration",
  "errorDetails": {
    "field": "name",
    "message": "Name field is required"
  }
}

This updated response structure helps you identify the exact field that caused the issue and provides a meaningful error message for troubleshooting.

Virtual Tags API Testing

Request	Notes	Additional info
GET /v1/virtual-tags /v1/virtual-tags/{id}	OK Users might get confused with the highlighted IDs since the actual V.Tag ID shows after the filters (maybe move to the beginning of the response?)	Actual V.Tag ID is at the end:
POST /v1/virtual-tags/{id}	FAILED Cannot create V.Tag with the same name 👍 (500) UPDATE: cannot update at all - get 500
PUT	FAILED

Still need help? Please feel free to reach out to our team at [email protected].

Virtual Tags

Finout Query Language API

Virtual Tag Metadata API

CostGuard API

Endpoint API