Cost estimates

Apply cost estimate

POST

https://api.costfluent.com

/v1/cost-estimates/apply

Bearer (API token)

Records that the change an estimate was posted for was applied, today in the workspace's time zone, naming the estimate by the reference it was posted under, so CI needs no read access. Each created or replaced resource names the one to three ids it got; an address the estimate does not name as created or replaced is ignored. The same apply again answers the estimate unchanged. The 30 days before the apply date and the 30 from it are measured once cost data covers them. The answer names the estimate, its state and the apply date only, never its figures. The body is at most 5 MiB.

Needs a token with submitCostEstimates on the workspace.

Apply cost estimate › Request Body

ApplyCostEstimateRequest

workspaceId

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

repository

string | null

pullRequest

integer | null · int32

plan

string | null

array | null

Apply cost estimate › Responses

Success

CostEstimateReceiptResponse

id

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

state

CostEstimateState · required

appliedOn

string | null · date

POST/v1/cost-estimates/apply

curl https://api.costfluent.com/v1/cost-estimates/apply \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "repository": "repository",
  "pullRequest": 0,
  "plan": "plan",
  "resources": [
    {
      "address": "address",
      "resourceIds": [
        "string"
      ]
    }
  ]
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "repository": "repository",
  "pullRequest": 0,
  "plan": "plan",
  "resources": [
    {
      "address": "address",
      "resourceIds": [
        "string"
      ]
    }
  ]
}

json

Example Responses

{
  "id": "id",
  "state": "state",
  "appliedOn": "2024-08-25"
}

json

application/json

Get cost estimate

GET

https://api.costfluent.com

/v1/cost-estimates/{estimateId}

Bearer (API token)

Returns one estimate with each resource's planned and, once reconciled, measured monthly cost and whether the reconciliation found it.

Needs a token with viewCosts on the workspace.

Get cost estimate › path Parameters

estimateId

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

Get cost estimate › Responses

Success

CostEstimateResponse

id

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

workspaceId

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

source

string · required

currency

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

state

CostEstimateState · required

CostEstimatePlannedResponse · required

resourceCount

integer · int32 · required

createdAt

string · date-time · required

repository

string | null

pullRequest

integer | null · int32

plan

string | null

sourceVersion

string | null

commit

string | null

url

string | null

appliedOn

string | null · date

array | null

updatedAt

string | null · date-time

closedAt

string | null · date-time

GET/v1/cost-estimates/{estimateId}

curl https://api.costfluent.com/v1/cost-estimates/:estimateId \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "id",
  "workspaceId": "workspaceId",
  "repository": "repository",
  "pullRequest": 0,
  "plan": "plan",
  "source": "source",
  "sourceVersion": "sourceVersion",
  "commit": "commit",
  "url": "url",
  "currency": "currency",
  "tag": {
    "key": "key",
    "value": "value"
  },
  "state": "state",
  "appliedOn": "2024-08-25",
  "outcome": "string",
  "planned": {
    "monthlyCostBefore": "monthlyCostBefore",
    "monthlyCostAfter": "monthlyCostAfter",
    "monthlyChange": "monthlyChange",
    "unpricedResources": 0
  },
  "actual": {
    "monthlyCostBefore": "monthlyCostBefore",
    "monthlyCostAfter": "monthlyCostAfter",
    "monthlyChange": "monthlyChange",
    "monthlyVariance": "monthlyVariance",
    "billingCurrency": "billingCurrency",
    "exchangeRate": "exchangeRate"
  },
  "resourceCount": 0,
  "resources": [
    {
      "address": "address",
      "type": "type",
      "change": "change",
      "monthlyCostBefore": "monthlyCostBefore",
      "monthlyCostAfter": "monthlyCostAfter",
      "plannedChange": "plannedChange",
      "resourceIds": [
        "string"
      ],
      "appliedResourceIds": [
        "string"
      ],
      "match": "string",
      "actualMonthlyCostBefore": "actualMonthlyCostBefore",
      "actualMonthlyCostAfter": "actualMonthlyCostAfter",
      "actualChange": "actualChange"
    }
  ],
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "closedAt": "2024-08-25T15:00:00Z"
}

json

application/json

List cost estimates

GET

https://api.costfluent.com

/v1/cost-estimates

Bearer (API token)

Returns the workspace's estimates newest first, each with its planned and measured totals and without its resources.

Needs a token with viewCosts on the workspace.

List cost estimates › query Parameters

workspaceId

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

state

string

repository

string | null

pullRequest

integer | null · int32

plan

string | null

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 cost estimates › Responses

Success

PaginatedResponseOfCostEstimateResponse

PaginationLinks · required

CostEstimateResponse[] · required

GET/v1/cost-estimates

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

Example Responses

{
  "links": {
    "self": "self",
    "first": "first",
    "prev": "prev",
    "next": "next",
    "last": "last"
  },
  "data": [
    {
      "id": "id",
      "workspaceId": "workspaceId",
      "repository": "repository",
      "pullRequest": 0,
      "plan": "plan",
      "source": "source",
      "sourceVersion": "sourceVersion",
      "commit": "commit",
      "url": "url",
      "currency": "currency",
      "tag": {
        "key": "key",
        "value": "value"
      },
      "state": "state",
      "appliedOn": "2024-08-25",
      "outcome": "string",
      "planned": {
        "monthlyCostBefore": "monthlyCostBefore",
        "monthlyCostAfter": "monthlyCostAfter",
        "monthlyChange": "monthlyChange",
        "unpricedResources": 0
      },
      "actual": {
        "monthlyCostBefore": "monthlyCostBefore",
        "monthlyCostAfter": "monthlyCostAfter",
        "monthlyChange": "monthlyChange",
        "monthlyVariance": "monthlyVariance",
        "billingCurrency": "billingCurrency",
        "exchangeRate": "exchangeRate"
      },
      "resourceCount": 0,
      "resources": [
        {
          "address": "address",
          "type": "type",
          "change": "change",
          "monthlyCostBefore": "monthlyCostBefore",
          "monthlyCostAfter": "monthlyCostAfter",
          "plannedChange": "plannedChange",
          "resourceIds": [
            "string"
          ],
          "appliedResourceIds": [
            "string"
          ],
          "match": "string",
          "actualMonthlyCostBefore": "actualMonthlyCostBefore",
          "actualMonthlyCostAfter": "actualMonthlyCostAfter",
          "actualChange": "actualChange"
        }
      ],
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z",
      "closedAt": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

Post cost estimate

POST

https://api.costfluent.com

/v1/cost-estimates

Bearer (API token)

Posts a planned change's monthly cost estimate for a pull request of a repository, or a named plan, as CI does on every push. The first post for a reference creates the estimate (201); a later one replaces it whole (200) until the change is applied, after which a post answers 409. Costfluent stores the figures as posted and prices nothing itself; a null monthly cost is one the estimator could not price, never zero. The answer names the estimate and its state only: the token CI posts with may hold submitCostEstimates alone and read no cost, and a token that may view costs reads the estimate by its id. A workspace holds at most 1,000 proposed or applied estimates. The body is at most 5 MiB.

Needs a token with submitCostEstimates on the workspace.

Post cost estimate › 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.

Post cost estimate › Request Body

SubmitCostEstimateRequest

workspaceId

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

source

string · minLength: 1 · required

currency

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

CostEstimateResourceRequest[] · minLength: 1 · required

repository

string | null

pullRequest

integer | null · int32

plan

string | null

sourceVersion

string | null

commit

string | null

url

string | null

Post cost estimate › Responses

The estimate posted earlier for the same reference, replaced

CostEstimateReceiptResponse

id

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

state

CostEstimateState · required

appliedOn

string | null · date

POST/v1/cost-estimates

curl https://api.costfluent.com/v1/cost-estimates \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "repository": "repository",
  "pullRequest": 0,
  "plan": "plan",
  "source": "source",
  "sourceVersion": "sourceVersion",
  "commit": "commit",
  "url": "url",
  "currency": "currency",
  "tag": {
    "key": "key",
    "value": "value"
  },
  "resources": [
    {
      "address": "address",
      "type": "type",
      "change": "change",
      "monthlyCostBefore": "monthlyCostBefore",
      "monthlyCostAfter": "monthlyCostAfter",
      "resourceIds": [
        "string"
      ]
    }
  ]
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "repository": "repository",
  "pullRequest": 0,
  "plan": "plan",
  "source": "source",
  "sourceVersion": "sourceVersion",
  "commit": "commit",
  "url": "url",
  "currency": "currency",
  "tag": {
    "key": "key",
    "value": "value"
  },
  "resources": [
    {
      "address": "address",
      "type": "type",
      "change": "change",
      "monthlyCostBefore": "monthlyCostBefore",
      "monthlyCostAfter": "monthlyCostAfter",
      "resourceIds": [
        "string"
      ]
    }
  ]
}

json

Example Responses

{
  "id": "id",
  "state": "state",
  "appliedOn": "2024-08-25"
}

json

application/json

Cost Filters Cost Data