Virtual Tags API V2
The Virtual Tags API V2 allows you to create, retrieve, update, and delete Virtual Tags programmatically.
Note: Reallocation is currently unsupported in the Virtual Tags API V2.
Prerequisites
Before calling this API, generate a Finout API token and include these headers in every request:
x-finout-client-idx-finout-secret-key
Rate Limits
GET
/v2/virtual-tags
Retrieve all Virtual Tags
50 req / min
GET
/v2/virtual-tags/{id}
Retrieve a Virtual Tag by ID
100 req / min
POST
/v2/virtual-tags
Create a new Virtual Tag
50 req / min
PUT
/v2/virtual-tags/{id}
Update an existing Virtual Tag
100 req / min
DELETE
/v2/virtual-tags/{id}
Delete a Virtual Tag
100 req / min
GET /Virtual Tags
Retrieves all Virtual Tag configurations for your account.
Prerequisites: Generate a Client ID and Secret Key from Finout to add in Headers. You also need a Virtual Tag ID.
Request
https://app.finout.io/v2/virtual-tags
Response
Response fields
requestId
string
Unique identifier for the request.
GET /Virtual Tag by ID
Retrieves the configuration of a specific Virtual Tag.
Prerequisites: Generate a Client ID and Secret Key from Finout to add in Headers. You also need a Virtual Tag ID.
Request
https://app.finout.io/v2/virtual-tags/{id}
Path parameter
id
string
The ID of the Virtual Tag to retrieve.
Response
POST /Virtual Tag
Creates a new Virtual Tag.
Prerequisites: Generate a Client ID and Secret Key from Finout to add in Headers.
Request
https://app.finout.io/v2/virtual-tags?setAsLive=true
Query parameters
setAsLive
boolean
No
Controls whether the newly created version becomes the Live version. Defaults to true if omitted.
setAsLive=true(default) — The new version is set as the Live version, making it active across Finout for filtering and grouping.setAsLive=false— The new version is created and added to the version timeline. Use this to stage versions without affecting other users.
Request body — custom string value
Request body — MegaBill key as destination
Body parameters
name
string
Yes
The name of the Virtual Tag.
defaultValue
string or object
Yes
Value assigned when no rules match. Use a string for a custom static value, or a { key, costCenter } object for a MegaBill key.
versionMetadata
object
No
Metadata about this version.
versionMetadata.changeDescription
string
No
A human-readable description of what changed in this version, recorded in the version history.
Response — custom string value
Response — MegaBill key
PUT /Virtual Tag
Updates an existing Virtual Tag. The full configuration is replaced.
Prerequisites: Generate a Client ID and Secret Key from Finout to add in Headers. You also need a Virtual Tag ID.
Request
https://app.finout.io/v2/virtual-tags/{id}?setAsLive=true
Path Parameter
id
string
Yes
The ID of the Virtual Tag to update.
Query Parameter
setAsLive
boolean
No
Controls whether the newly created version becomes the Live version. Defaults to true if omitted.
setAsLive=true(default) — The new version is set as the Live version, making it active across Finout for filtering and grouping.setAsLive=false— The new version is created and added to the version timeline. Use this to stage versions without affecting other users.
Request body — custom string value
Request body — MegaBill key as destination
Body parameters
name
string
Yes
The name of the Virtual Tag.
defaultValue
string or object
Yes
Value assigned when no rules match. Use a string for a custom static value, or a { key, costCenter } object for a MegaBill key.
versionMetadata
object
No
Metadata about this version.
versionMetadata.changeDescription
string
No
A human-readable description of the change, recorded in the version history.
Response — custom string value
Response — MegaBill key
DELETE /Virtual Tag
Deletes a Virtual Tag.
Prerequisites: Generate a Client ID and Secret Key from Finout to add in Headers. You also need a Virtual Tag ID.
Request
https://app.finout.io/v2/virtual-tags/{id}
Path parameter
id
string
The ID of the Virtual Tag to delete.
Response
Warning: Deleting a Virtual Tag also removes all its version history. This action cannot be undone.
Virtual Tag objects
The Virtual Tag object represents a configuration used for resource allocation and filtering.
id
string
The unique identifier of the Virtual Tag.
"2e29ad96-3616-43d7-9858-a00477457e6a"
name
string
The name of the Virtual Tag.
"Team Allocation"
defaultValue
string or object
Value assigned when no rules match. Can be a static string or a { key, costCenter } MegaBill key object.
"Untagged" or { "key": "eks_cluster_name", "costCenter": "AWS" }
createdBy
string
Email of the user who created the Virtual Tag.
"sam.smith@finout.io"
updatedBy
string
Email of the user who last updated the Virtual Tag.
"sam.smith@finout.io"
createdAt
string (ISO-8601)
Timestamp when the Virtual Tag was created.
"2024-09-09T21:47:55.000Z"
updatedAt
string (ISO-8601)
Timestamp when the Virtual Tag was last updated.
"2024-11-13T17:55:07.000Z"
Rules object definition
to
string or object
The tag value to assign when the rule matches. Use a string for a static value, or a { key, costCenter } object for a MegaBill key.
"Backend" or { "key": "k8s_cluster", "costCenter": "Kubernetes" }
timeframe
object
Optional. Applies the rule only within a defined date range. Uses unix timestamps in milliseconds: { "from": <timestamp>, "to": <timestamp> }. Omit to for an open-ended range.
{ "from": 1756166400000, "to": 1756166400100 }
Error handling
400 Bad Request
Malformed request or missing required parameters.
Check the request body structure and resubmit.
401 Unauthorized
Missing or invalid credentials.
Verify your x-finout-client-id and x-finout-secret-key headers.
403 Forbidden
Valid credentials but insufficient permissions.
Check the Virtual Tag's write ACL or contact Finout support.
404 Not Found
The requested Virtual Tag ID does not exist.
Confirm the ID with GET /v2/virtual-tags.
422 Unprocessable Request
Request structure is valid JSON but fails business validation.
Review the Virtual Tag rule and filter composition.
429 Too Many Requests
Rate limit exceeded.
Reduce request frequency and retry after the window resets.
500 Internal Server Error
Unexpected server-side error.
Retry the request. If the issue persists, contact Finout Support.
FAQs
What happens if I exceed the rate limits?
The API returns a 429 Too Many Requests response. Use the following response headers to monitor your rate limit consumption:
ratelimitx-account-ratelimit-*x-endpoint-ratelimit-*
In what order are rules evaluated?
Rules are evaluated top to bottom. Order your rules from most specific to most general, and place your catch-all rules last.
How many rules can a Virtual Tag have?
1,000 rules per Virtual Tag. If you need more granular allocation, consider splitting your logic across multiple Virtual Tags or using nested AND/OR filter conditions within a single rule.
How many versions each Virtual Tag can have?
Each Virtual Tag retains up to 100 versions for one year — when a 101st version is created, the oldest non-live version is deleted automatically.
Does a POST or PUT request always create a new Live version?
By default, yes. Every successful POST or PUT creates a new version that becomes Live by default. To create a new version without affecting the current Live, include setAsLive=false in the request URL. This stages the version on the history timeline without making it Live.
Do I need to include displayName in filter objects when creating or updating a Virtual Tag?
No. displayName is a read-only convenience field that Finout returns in GET responses for human readability. You do not need to include it in POST or PUT request bodies.
What is the difference between the is and oneOf operators?
is matches a single exact string value — pass a string in value. oneOf matches if the field equals any item in an array — pass an array in value. Use oneOf whenever you need to match more than one value; is for a single exact match only.
Can I create Virtual Tags with reallocation via the API?
No. Reallocation rules are not supported in the Virtual Tags API.
What ACL permissions does a Virtual Tag get when created via the API?
Read access is always public — all users in your account can view and use the Virtual Tag for filtering and grouping. Write access defaults to your account-level ACL setting.
What happens to dashboards and views that reference a deleted Virtual Tag?
They lose that Virtual Tag dimension permanently. Finout does not cascade-update any saved views, dashboard widgets, or reports that referenced the deleted tag. Verify all downstream dependencies before sending a DELETE request.
What is changeDescription and how do I set it?
changeDescription is an optional human-readable note describing what changed in that version. Include a changeDescription string in the body of a Virtual Tag V2 POST or PUT request.
Last updated
Was this helpful?