Virtual Tag Versions API V2 (Beta)

The Virtual Tag Versions API lets you retrieve the full version history of a Virtual Tag and inspect historical configuration snapshot — including its tagging rules, default value, and change description.

Use this API to audit changes over time and compare configurations across versions.

Note: Each time a Virtual Tag is saved in Finout, a new version is automatically created. Only one version is live at any time and can be used by users when filtering or grouping by virtual tags in Finout.

---

Prerequisites

Before calling either endpoint, make sure you have:

1. A Finout API token. Generate a Finout API token and add these headers to every request:

   • x-finout-client-id

   • x-finout-secret-key

2. The ID of the Virtual Tag whose versions you want to retrieve. Use the Virtual Tags API V2 to get a Virtual Tag ID.

---

How it works

Every Virtual Tag can have multiple versions. Each version contains:

• Metadata — who created it and when

• Change description — an optional note describing what changed

• Configuration snapshot — the complete tagging rules and default value at the time of save

There are two endpoints:

• List all versions for a Virtual Tag, paginated and sortable

• Fetch a single version by ID to inspect its full configuration

---

Rate Limits

Route	Rate Limit (per account, per route)
GET /v2/virtual-tags/{id}/versions	50 req / min
GET /v2/virtual-tags/{vtagId}/versions/{id}	100 req / min

---

GET /Virtual Tag Versions

Returns a paginated list of all versions for a given Virtual Tag, sorted by creation date.

Request

GET https://app.finout.io/v2/virtual-tags/{id}/versions

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The Virtual Tag identifier

Query Parameters

Parameter	Type	Required	Description
from	integer (unix timestamp in milliseconds)	No	Return versions with createdAt on or after this timestamp
to	integer (unix timestamp in milliseconds)	No	Return versions with createdAt on or before this timestamp
pageSize	integer	No	Results per page. Default: 50. Max: 100
cursor	string	No	Cursor for fetching the next page
sortDirection	string	No	asc or desc. Default: desc

Important — pagination: If your initial request includes from, to, pageSize, or sortDirection, you must repeat those same parameters alongside cursor on every subsequent request. The cursor encodes position only — omitting these parameters on a cursor request will return inconsistent results.

Response

{
  "requestId": "828a4454-5a41-4473-9fea-15ce7b3557f4",
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  },
  "data": [
    {
      "id": "eb14e00a-97a8-4af3-84c5-f3dd07d847d8",
      "createdBy": "[email protected]",
      "createdAt": "2026-03-31T18:23:48.701Z",
      "isLive": true
    },
    {
      "id": "194f60db-7d2b-4599-b1c2-0fb58160a2d7",
      "createdBy": "[email protected]",
      "createdAt": "2026-03-24T18:07:47.475Z",
      "isLive": false
    },
    {
      "id": "36aea575-cb7f-445f-963e-9e68c4a3a46b",
      "createdBy": "[email protected]",
      "createdAt": "2026-03-24T16:59:49.766Z",
      "isLive": false,
      "changeDescription": "Duplicate from virtual tag \"AG/Team\""
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Version identifier
createdAt	string (ISO-8601)	Timestamp when this version was created
createdBy	string (email)	User who saved this version
changeDescription	string	Optional description of what changed
isLive	boolean	true if this is the currently active version

Pagination Fields

Field	Type	Description
hasMore	boolean	Whether additional pages are available
nextCursor	string	Pass this value as cursor to fetch the next page

---

GET /Virtual Tag Version by ID

Returns a single version, including its full configuration snapshot (rules and default value).

{% hint style="info" %} Note: To fetch a specific version, you must first call GET /Virtual Tag Versions to obtain a versionId. {% endhint %}

Request

GET https://app.finout.io/v2/virtual-tags/{vtagId}/versions/{id}

Path Parameters

Parameter	Type	Required	Description
vtagId	string	Yes	The Virtual Tag identifier
id	string	Yes	The Version identifier

Response

{
  "requestId": "c85f0423-7048-432b-a144-73f76c2e0512",
  "data": {
    "id": "aba7efe5-de85-4f4b-bd89-0861d140c018",
    "createdBy": "[email protected]",
    "createdAt": "2026-03-25T13:19:06.200Z",
    "isLive": false,
    "changeDescription": "doc demo 1",
    "versionData": {
      "rules": [
        {
          "to": {
            "key": "4f816fc1-6b3a-4902-b6b5-9759ba5ca83c",
            "costCenter": "Virtual Tags",
            "type": "virtual_tag"
          },
          "filters": {
            "costCenter": "AWS",
            "key": "operation",
            "displayName": "API Operation",
            "operator": "oneOf",
            "value": ["AAAA"],
            "type": "billing_enrichment"
          }
        }
      ],
      "defaultValue": "Untagged"
    }
  }
}

Response Fields

Field	Type	Description
id	string	Version identifier
createdAt	string (ISO-8601)	Timestamp when this version was created
createdBy	string (email)	User who saved this version
changeDescription	string	Optional description of what changed
isLive	boolean	true if this is the currently active version
versionData	object	Full configuration snapshot for this version

Version Data Fields

Field	Type	Description
rules	array	The list of matching rules at the time of save
defaultValue	string	The value assigned when no rules match

For the full definition of the rules object structure, see Virtual Tags API V2 — Virtual Tags Objects.

---

Error Reference

Error Code	Description	When it occurs
UNAUTHORIZED	Authentication credentials are missing or invalid	Missing or invalid auth headers
FORBIDDEN	You do not have permission to access this Virtual Tag	Access denied by ACL
VTAG_NOT_FOUND	The specified Virtual Tag was not found	Invalid id
VTAG_VERSION_NOT_FOUND	The specified version was not found	Invalid versionId

---

FAQs

Does every Virtual Tag save create a new version?

Yes. Every time a Virtual Tag is saved via the API a new version is automatically created.

---

How many versions are retained per Virtual Tag?

Up to 100 versions are retained per Virtual Tag, for up to 1 year. Versions beyond these limits are removed automatically as long as they are not the live version, starting from the oldest.

---

Is the Versions API V2 read-only?

Yes. The Versions API only supports GET operations. You can list versions and retrieve version snapshots, but you cannot create, delete, or promote versions directly via this API.

To restore a previous configuration and resubmit it as a PUT request to Virtual Tags API V2. See How do I restore a previous version?.

---

How do I get a versionId?

Call GET /v2/virtual-tags/{id}/versions first. This returns a paginated list of all versions for the Virtual Tag, each with an id, createdAt, createdBy, isLive, and optional changeDescription. Use the id from this list as the versionId in GET /v2/virtual-tags/{vtagId}/versions/{id}.

---

What does isLive mean?

isLive: true marks the version that is currently active — the configuration Finout is using for cost allocation right now when selecting this virtual tag in filter or group by. Only one version per Virtual Tag has isLive: true at any time. All other versions are historical snapshots.

---

How does pagination work?

The list endpoint returns up to pageSize results per page (default: 50, max: 100). When more pages exist, the response includes pagination.hasMore: true and a pagination.nextCursor value. Pass that value as the cursor query parameter in your next request. Continue until hasMore: false.

GET /v2/virtual-tags/{id}/versions?cursor=<nextCursor>

---

How do I restore a previous version?

The Versions API is read-only, so there is no direct rollback endpoint. To restore a previous version:

1. Call GET /v2/virtual-tags/{id}/versions to find the version you want.

2. Call GET /v2/virtual-tags/{id}/versions/{versionId} to retrieve its full configuration snapshot.

3. Extract versionData.rules and versionData.defaultValue from the response.

4. Submit a PUT /v2/virtual-tags/{id} request to Virtual Tags API V2 with those values as the request body.

This creates a new version with the restored configuration, which then becomes the live version.

---

Does restoring a version delete the version history?

No. Submitting a PUT with a previous version's configuration creates a new version — it does not overwrite or remove any existing version history. All prior versions remain accessible via the Versions API.

---

Can I restore a version if the Virtual Tag has been deleted?

No. Deleting a Virtual Tag also removes all its associated version history.

---

What are the rate limits for the Versions endpoints?

Rate limits are per account, per endpoint, measured in requests per minute. They are not shared with other Virtual Tags API endpoints.

Endpoint	Rate limit
GET /v2/virtual-tags/{id}/versions	100 req / min
GET /v2/virtual-tags/{vtagId}/versions/{id}	300 req / min

---

What happens if I exceed the rate limit?

The API returns a 429 Too Many Requests response. Use the following response headers to monitor your rate limit consumption:

• ratelimit

• x-account-ratelimit-*

• x-endpoint-ratelimit-*

---