Allocation

List allocation rules

GET

https://api.costfluent.com

/v1/allocation/rules

Bearer (API token)

Returns the workspace's rules in compiled precedence order, paged. The order is the meaning of the set, so reading every page in turn is also the export.

Needs a token with viewCostAllocation on the workspace.

List allocation rules › 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 allocation rules › Responses

Success

PaginatedResponseOfAllocationRuleResponse

PaginationLinks · required

AllocationRuleResponse[] · required

Create an allocation rule

POST

https://api.costfluent.com

/v1/allocation/rules

Bearer (API token)

Needs a token with manageCostAllocation on the workspace.

Create an allocation rule › 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 an allocation rule › Request Body

CreateAllocationRuleRequest

workspaceId

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

name

string · required

filter

string · required

segmentId

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

priority

integer · int32

isEnabled

boolean

Create an allocation rule › Responses

Created

AllocationRuleResponse

id

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

name

string · required

priority

integer · int32 · required

filter

string · required

costKind

string · required

segmentId

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

isEnabled

boolean · required

createdAt

string · date-time · required

segmentName

string | null

costCentre

string | null

updatedAt

string | null · date-time

POST/v1/allocation/rules

curl https://api.costfluent.com/v1/allocation/rules \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "name": "name",
  "priority": 0,
  "filter": "filter",
  "segmentId": "segmentId",
  "isEnabled": true
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "name": "name",
  "priority": 0,
  "filter": "filter",
  "segmentId": "segmentId",
  "isEnabled": true
}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "priority": 0,
  "filter": "filter",
  "costKind": "costKind",
  "segmentId": "segmentId",
  "segmentName": "segmentName",
  "costCentre": "costCentre",
  "isEnabled": true,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z"
}

json

application/json

Update an allocation rule

PUT

https://api.costfluent.com

/v1/allocation/rules/{ruleId}

Bearer (API token)

Needs a token with manageCostAllocation on the workspace.

Update an allocation rule › path Parameters

ruleId

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

Update an allocation rule › query Parameters

workspaceId

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

Update an allocation rule › 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 an allocation rule › Request Body

UpdateAllocationRuleRequest

name

string · required

filter

string · required

segmentId

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

priority

integer | null · int32

isEnabled

boolean | null

Update an allocation rule › Responses

Success

AllocationRuleResponse

id

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

name

string · required

priority

integer · int32 · required

filter

string · required

costKind

string · required

segmentId

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

isEnabled

boolean · required

createdAt

string · date-time · required

segmentName

string | null

costCentre

string | null

updatedAt

string | null · date-time

PUT/v1/allocation/rules/{ruleId}

curl 'https://api.costfluent.com/v1/allocation/rules/:ruleId?workspaceId=<string>' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "priority": 0,
  "filter": "filter",
  "segmentId": "segmentId",
  "isEnabled": true
}'

Example Request Body

{
  "name": "name",
  "priority": 0,
  "filter": "filter",
  "segmentId": "segmentId",
  "isEnabled": true
}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "priority": 0,
  "filter": "filter",
  "costKind": "costKind",
  "segmentId": "segmentId",
  "segmentName": "segmentName",
  "costCentre": "costCentre",
  "isEnabled": true,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z"
}

json

application/json

Delete an allocation rule

DELETE

https://api.costfluent.com

/v1/allocation/rules/{ruleId}

Bearer (API token)

Allocation is evaluated at query time, so removing a rule restates every past month immediately.

Needs a token with manageCostAllocation on the workspace.

Delete an allocation rule › path Parameters

ruleId

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

Delete an allocation rule › query Parameters

workspaceId

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

Delete an allocation rule › 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 an allocation rule › Responses

No Content

No data returned

Reorder the allocation rule set

POST

https://api.costfluent.com

/v1/allocation/rules/order

Bearer (API token)

Needs a token with manageCostAllocation on the workspace.

Reorder the allocation rule set › Request Body

ReorderAllocationRulesRequest

workspaceId

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

ruleIds

AllocationRulePublicId[]

Reorder the allocation rule set › Responses

Success

AllocationRuleResponse[]

AllocationRuleResponse

id

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

name

string · required

priority

integer · int32 · required

filter

string · required

costKind

string · required

segmentId

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

isEnabled

boolean · required

createdAt

string · date-time · required

segmentName

string | null

costCentre

string | null

updatedAt

string | null · date-time

POST/v1/allocation/rules/order

curl https://api.costfluent.com/v1/allocation/rules/order \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "ruleIds": [
    "string"
  ]
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "ruleIds": [
    "string"
  ]
}

json

Example Responses

[
  {
    "id": "id",
    "name": "name",
    "priority": 0,
    "filter": "filter",
    "costKind": "costKind",
    "segmentId": "segmentId",
    "segmentName": "segmentName",
    "costCentre": "costCentre",
    "isEnabled": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
]

json

application/json

Read allocation coverage

GET

https://api.costfluent.com

/v1/allocation/coverage

Bearer (API token)

Needs a token with viewCostAllocation on the workspace.

Read allocation coverage › query Parameters

workspaceId

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

startDate

string · date · required

The window's first day, included.

endDate

string · date · required

The window's last day, included, so March is 2026-03-01 to 2026-03-31. A window covers at most 366 days.

costBasis

string

Default: ActualCost

Read allocation coverage › Responses

Success

AllocationCoverageResponse

startDate

string · date · required

endDate

string · date · required

costBasis

string · required

AllocationCoverageCurrency[] · required

GET/v1/allocation/coverage

curl 'https://api.costfluent.com/v1/allocation/coverage?workspaceId=<string>&startDate=<string>&endDate=<string>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "costBasis": "costBasis",
  "currencies": [
    {
      "billingCurrency": "billingCurrency",
      "totalCost": "totalCost",
      "directCost": "directCost",
      "sharedCost": "sharedCost",
      "undistributedSharedCost": "undistributedSharedCost",
      "unallocatedCost": "unallocatedCost",
      "unallocatedRecordCount": 0,
      "recordCount": 0,
      "coverage": 0,
      "segments": [
        {
          "segmentId": "segmentId",
          "name": "name",
          "costCentre": "costCentre",
          "directCost": "directCost",
          "sharedCost": "sharedCost",
          "allocatedCost": "allocatedCost",
          "recordCount": 0
        }
      ],
      "pools": [
        {
          "segmentId": "segmentId",
          "label": "label",
          "method": "method",
          "cost": "cost",
          "distributedCost": "distributedCost",
          "residual": "residual",
          "recordCount": 0,
          "shares": [
            {
              "segmentId": "segmentId",
              "share": "share"
            }
          ]
        }
      ]
    }
  ]
}

json

application/json

List segments

GET

https://api.costfluent.com

/v1/segments

Bearer (API token)

Returns every segment cost can be assigned to in a workspace.

Needs a token with viewCostAllocation on the workspace.

List segments › 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 segments › Responses

Success

PaginatedResponseOfSegmentResponse

PaginationLinks · required

SegmentResponse[] · required

GET/v1/segments

curl 'https://api.costfluent.com/v1/segments?workspaceId=<string>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "links": {
    "self": "self",
    "first": "first",
    "prev": "prev",
    "next": "next",
    "last": "last"
  },
  "data": [
    {
      "id": "id",
      "teamId": "string",
      "teamLabel": "teamLabel",
      "teamName": "teamName",
      "product": "product",
      "costCentre": "costCentre",
      "isShared": true,
      "label": "label",
      "split": {
        "method": "method",
        "targets": [
          {
            "segmentId": "segmentId",
            "percent": 0
          }
        ]
      },
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

Create a segment

POST

https://api.costfluent.com

/v1/segments

Bearer (API token)

Needs a token with manageCostAllocation on the workspace.

Create a segment › Headers

Idempotency-Key

string · minLength: 1 · maxLength: 255

Create a segment › Request Body

CreateSegmentRequest

workspaceId

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

teamLabel

string | null

product

string

costCentre

string

isShared

boolean

label

string | null

Create a segment › Responses

Created

SegmentResponse

id

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

teamLabel

string · required

product

string · required

costCentre

string · required

isShared

boolean · required

label

string · required

createdAt

string · date-time · required

teamName

string | null

updatedAt

string | null · date-time

POST/v1/segments

curl https://api.costfluent.com/v1/segments \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "teamId": "string",
  "teamLabel": "teamLabel",
  "product": "product",
  "costCentre": "costCentre",
  "isShared": true,
  "label": "label",
  "split": {
    "method": "proportional",
    "targets": [
      {
        "segmentId": "segmentId",
        "percent": 0
      }
    ]
  }
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "teamId": "string",
  "teamLabel": "teamLabel",
  "product": "product",
  "costCentre": "costCentre",
  "isShared": true,
  "label": "label",
  "split": {
    "method": "proportional",
    "targets": [
      {
        "segmentId": "segmentId",
        "percent": 0
      }
    ]
  }
}

json

Example Responses

{
  "id": "id",
  "teamId": "string",
  "teamLabel": "teamLabel",
  "teamName": "teamName",
  "product": "product",
  "costCentre": "costCentre",
  "isShared": true,
  "label": "label",
  "split": {
    "method": "method",
    "targets": [
      {
        "segmentId": "segmentId",
        "percent": 0
      }
    ]
  },
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z"
}

json

application/json

Update a segment

PUT

https://api.costfluent.com

/v1/segments/{segmentId}

Bearer (API token)

Renames a direct segment, or changes a shared segment's label and split.

Needs a token with manageCostAllocation on the workspace.

Update a segment › path Parameters

segmentId

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

Update a segment › query Parameters

workspaceId

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

Update a segment › 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 a segment › Request Body

UpdateSegmentRequest

teamLabel

string | null

product

string | null

costCentre

string | null

label

string | null

Update a segment › Responses

Success

SegmentResponse

id

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

teamLabel

string · required

product

string · required

costCentre

string · required

isShared

boolean · required

label

string · required

createdAt

string · date-time · required

teamName

string | null

updatedAt

string | null · date-time

PUT/v1/segments/{segmentId}

curl 'https://api.costfluent.com/v1/segments/:segmentId?workspaceId=<string>' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "teamId": "string",
  "teamLabel": "teamLabel",
  "product": "product",
  "costCentre": "costCentre",
  "label": "label",
  "split": {
    "method": "proportional",
    "targets": [
      {
        "segmentId": "segmentId",
        "percent": 0
      }
    ]
  }
}'

Example Request Body

{
  "teamId": "string",
  "teamLabel": "teamLabel",
  "product": "product",
  "costCentre": "costCentre",
  "label": "label",
  "split": {
    "method": "proportional",
    "targets": [
      {
        "segmentId": "segmentId",
        "percent": 0
      }
    ]
  }
}

json

Example Responses

{
  "id": "id",
  "teamId": "string",
  "teamLabel": "teamLabel",
  "teamName": "teamName",
  "product": "product",
  "costCentre": "costCentre",
  "isShared": true,
  "label": "label",
  "split": {
    "method": "method",
    "targets": [
      {
        "segmentId": "segmentId",
        "percent": 0
      }
    ]
  },
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z"
}

json

application/json

Delete a segment

DELETE

https://api.costfluent.com

/v1/segments/{segmentId}

Bearer (API token)

Refused with 409 in_use while any rule still assigns cost to it, any budget measures it, a shared segment's split names it, or a cost report, cost alert or saved filter filters to it.

Needs a token with manageCostAllocation on the workspace.

Delete a segment › path Parameters

segmentId

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

Delete a segment › query Parameters

workspaceId

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

Delete a segment › 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 a segment › Responses

No Content

No data returned

Preview an allocation rule

POST

https://api.costfluent.com

/v1/allocation/rules/preview

Bearer (API token)

Computes what the rule would move without creating it. Allocation is evaluated at query time, so enabling a rule restates history immediately.

Needs a token with viewCostAllocation on the workspace.

Preview an allocation rule › Request Body

PreviewAllocationRuleRequest

workspaceId

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

startDate

string · date · required

endDate

string · date · required

filter

string · required

segmentId

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

priority

integer · int32

Preview an allocation rule › Responses

Success

AllocationDryRunResponse[]

AllocationDryRunResponse

billingCurrency

string · pattern: ^[A-Z]{3}$ · required

movedCost

string · decimal · pattern: ^-?[0-9]+(\.[0-9]{1,… · required

movedRecordCount

integer · int64 · required

coverageBefore

number · double · required

coverageAfter

number · double · required

AllocationDryRunSegmentChangeResponse[] · required

POST/v1/allocation/rules/preview

curl https://api.costfluent.com/v1/allocation/rules/preview \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "filter": "filter",
  "segmentId": "segmentId",
  "priority": 0
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "filter": "filter",
  "segmentId": "segmentId",
  "priority": 0
}

json

Example Responses

[
  {
    "billingCurrency": "billingCurrency",
    "movedCost": "movedCost",
    "movedRecordCount": 0,
    "coverageBefore": 0,
    "coverageAfter": 0,
    "segmentChanges": [
      {
        "name": "name",
        "costCentre": "costCentre",
        "allocatedBefore": "allocatedBefore",
        "allocatedAfter": "allocatedAfter",
        "delta": "delta"
      }
    ]
  }
]

json

application/json

Annotations