Virtual Tags

List virtual tags

GET

https://api.costfluent.com

/v1/virtual-tags

Bearer (API token)

Returns the workspace's enabled virtual tags. The templates a workspace is created with are listed once enabled in the console, or once a tag is created under one's key.

Needs a token with viewTags on the workspace.

List virtual tags › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

page

integer · int32

The page to return, counted from 1. A page below 1 reads page 1; one past the last returns no items.

Default: 1

limit

integer · int32

Items per page, from 1 to 100. A larger value is clamped to 100, a smaller one to 1.

Default: 20

List virtual tags › Responses

Success

PaginatedResponseOfVirtualTagResponse

PaginationLinks · required

VirtualTagResponse[] · required

Create virtual tag

POST

https://api.costfluent.com

/v1/virtual-tags

Bearer (API token)

Creates a new virtual tag.

Needs a token with manageTags on the workspace.

Create virtual tag › Headers

Idempotency-Key

string · minLength: 1 · maxLength: 255

A unique value, at most 255 printable ASCII characters, such as a UUID, that makes retrying this create safe. A retry with the same key and the same request within 24 hours answers the first response again, marked Idempotent-Replayed: true, and creates nothing; the same key with another request answers 422 idempotency_key_reused. A key is kept only for a create that succeeded. Without it, every request creates.

Create virtual tag › Request Body

CreateVirtualTagRequest

workspaceId

WorkspacePublicId · minLength: 1 · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

key

string · required

description

string | null

defaultValue

string | null

collapsedTagKeys

string[]

VirtualTagRuleRequest[]

Create virtual tag › Responses

Created

VirtualTagCreatedResponse

id

VirtualTagPublicId · pattern: ^vtag_[A-Za-z0-9_-]{… · required

key

string · required

POST/v1/virtual-tags

curl https://api.costfluent.com/v1/virtual-tags \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "key": "key",
  "description": "description",
  "defaultValue": "defaultValue",
  "collapsedTagKeys": [
    "string"
  ],
  "rules": [
    {
      "value": "value",
      "filter": "filter"
    }
  ]
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "key": "key",
  "description": "description",
  "defaultValue": "defaultValue",
  "collapsedTagKeys": [
    "string"
  ],
  "rules": [
    {
      "value": "value",
      "filter": "filter"
    }
  ]
}

json

Example Responses

{
  "id": "id",
  "key": "key"
}

json

application/json

Get virtual tag

GET

https://api.costfluent.com

/v1/virtual-tags/{virtualTagId}

Bearer (API token)

Returns a specific virtual tag.

Needs a token with viewTags on the workspace.

Get virtual tag › path Parameters

virtualTagId

VirtualTagPublicId · pattern: ^vtag_[A-Za-z0-9_-]{… · required

Get virtual tag › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

Get virtual tag › Responses

Success

VirtualTagResponse

id

VirtualTagPublicId · pattern: ^vtag_[A-Za-z0-9_-]{… · required

key

string · required

collapsedTagKeys

string[] · required

VirtualTagRuleResponse[] · required

createdAt

string · date-time · required

description

string | null

defaultValue

string | null

updatedAt

string | null · date-time

Update virtual tag

PATCH

https://api.costfluent.com

/v1/virtual-tags/{virtualTagId}

Bearer (API token)

Updates a virtual tag and returns it as stored. Refused with 409 conflict when the new key is another enabled virtual tag's in the workspace.

Needs a token with manageTags on the workspace.

Update virtual tag › path Parameters

virtualTagId

VirtualTagPublicId · pattern: ^vtag_[A-Za-z0-9_-]{… · required

Update virtual tag › Headers

If-Match

string

Applies the write only while the resource still has this ETag, and answers 412 precondition_failed otherwise. Without it, the last write wins.

Update virtual tag › Request Body

UpdateVirtualTagRouteRequest

workspaceId

WorkspacePublicId · minLength: 1 · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

key

string | null

description

string | null

clearDescription

boolean

defaultValue

string | null

clearDefaultValue

boolean

collapsedTagKeys

array | null

Update virtual tag › Responses

Success

VirtualTagResponse

id

VirtualTagPublicId · pattern: ^vtag_[A-Za-z0-9_-]{… · required

key

string · required

collapsedTagKeys

string[] · required

VirtualTagRuleResponse[] · required

createdAt

string · date-time · required

description

string | null

defaultValue

string | null

updatedAt

string | null · date-time

PATCH/v1/virtual-tags/{virtualTagId}

curl https://api.costfluent.com/v1/virtual-tags/:virtualTagId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "key": "key",
  "description": "description",
  "clearDescription": true,
  "defaultValue": "defaultValue",
  "clearDefaultValue": true,
  "collapsedTagKeys": [
    "string"
  ],
  "rules": [
    {
      "value": "value",
      "filter": "filter"
    }
  ]
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "key": "key",
  "description": "description",
  "clearDescription": true,
  "defaultValue": "defaultValue",
  "clearDefaultValue": true,
  "collapsedTagKeys": [
    "string"
  ],
  "rules": [
    {
      "value": "value",
      "filter": "filter"
    }
  ]
}

json

Example Responses

{
  "id": "id",
  "key": "key",
  "description": "description",
  "defaultValue": "defaultValue",
  "collapsedTagKeys": [
    "string"
  ],
  "rules": [
    {
      "value": "value",
      "filter": "filter"
    }
  ],
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z"
}

json

application/json

Delete virtual tag

DELETE

https://api.costfluent.com

/v1/virtual-tags/{virtualTagId}

Bearer (API token)

Deletes a virtual tag. Refused with 409 in_use, naming them, while cost reports, cost alerts or saved filters filter or group by it.

Needs a token with manageTags on the workspace.

Delete virtual tag › path Parameters

virtualTagId

VirtualTagPublicId · pattern: ^vtag_[A-Za-z0-9_-]{… · required

Delete virtual tag › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

Delete virtual tag › Headers

If-Match

string

Applies the write only while the resource still has this ETag, and answers 412 precondition_failed otherwise. Without it, the last write wins.

Delete virtual tag › Responses

No Content

No data returned

Utility Workspace Providers