Cost Data

Get cost data

GET

https://api.costfluent.com

/v1/costs

Bearer (API token)

Returns cost data grouped by up to three ordered dimensions, filtered by the supplied cost filter. A page holds up to 5,000 rows, and paging reaches 100,000 rows (page × limit): a larger read splits its date window into shorter ranges. Each row's dimensions object holds one value per groupBy slot, keyed by the slot: the dimension's name with a capital first letter (ServiceName for groupBy=serviceName), followed by a colon and the key for a tag or virtual tag (Tag:team, VirtualTag:vtag_...). An ungrouped read has an empty dimensions.

Needs a token with viewCosts; a workspace token lists its own workspace only.

Get cost data › query Parameters

startDate

string · date · required

endDate

string · date · required

workspaceId

granularity

string

Default: day

groupBy

array | null · style: form · explode: true

Up to three grouping slots, repeated in order: groupBy=serviceName&groupBy=tag:team. A slot is one of provider, providerName, subAccount, serviceName, region, resourceName, chargeCategory, segment, cluster, namespace, billingAccount, serviceCategory, serviceSubcategory, usageUnit, chargeClass, tagged, resourceId, commitmentStatus, commitmentType, pricingCategory, sku, commitmentId, operation, chargeDescription, resourceType, productFamily, skuId, invoiceId, invoiceIssuer, billingPeriod, resourceGroup, or tag:<key> for a tag key and virtualTag:<id> for a virtual tag's id. Names match in any case. A segment or virtualTag slot needs workspaceId. The operation's description says how each row's dimensions is keyed.

cloudAccountIds

array | null · style: form · explode: true

filter

string | null

includeCredits

boolean

Default: false

includeRefunds

boolean

Default: true

includeTax

boolean

Default: true

amortize

boolean

Default: true

measure

string

dataVersion

string | null

The meta.dataVersion of an earlier page of the same read. With it, a page is refused with 409 when a sync changed the data the read covers since that page, rather than read from the changed data, whose rows can repeat or skip ones already read; read the window again from page 1. The links of a request that sends it carry it. Omitted, each page is read from whatever is committed when it is requested.

page

integer · int32

The page to return, counted from 1. Paging reaches 100,000 rows (page × limit); a page past that is refused, and a longer read splits its date window instead.

Default: 1

limit

integer · int32

Rows per page, from 1 to 5,000. A value outside that range is refused.

Default: 20

Get cost data › Responses

Success

CostDataResponse

PaginationLinks · required

CostDataPoint[] · required

CostDataMeta · required

GET/v1/costs

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

Example Responses

{
  "links": {
    "self": "self",
    "first": "first",
    "prev": "prev",
    "next": "next",
    "last": "last"
  },
  "data": [
    {
      "date": "2024-08-25",
      "cost": "cost",
      "listCost": "listCost",
      "amortizedCost": "amortizedCost",
      "currency": "currency",
      "dimensions": {
        "key": "string"
      },
      "quantity": 0,
      "unit": "unit"
    }
  ],
  "meta": {
    "startDate": "2024-08-25",
    "endDate": "2024-08-25",
    "granularity": "granularity",
    "measure": "measure",
    "totalRecords": 0,
    "totalCost": "totalCost",
    "currency": "currency",
    "presentation": {
      "conversions": [
        {
          "sourceCurrency": "sourceCurrency",
          "sourceAmount": "sourceAmount",
          "convertedAmount": "convertedAmount",
          "method": "method",
          "source": "source",
          "description": "description"
        }
      ],
      "unconverted": [
        {
          "currency": "currency",
          "amount": "amount"
        }
      ],
      "totalsByCurrency": [
        {
          "currency": "currency",
          "amount": "amount"
        }
      ]
    },
    "commitmentDiscounts": "commitmentDiscounts",
    "historyFloor": "2024-08-25",
    "dataThrough": "2024-08-25",
    "dataVersion": "dataVersion"
  }
}

json

application/json

Get cost forecast

GET

https://api.costfluent.com

/v1/costs/forecast

Bearer (API token)

Returns cost forecast for the upcoming months.

Needs a token with viewCosts on the workspace.

Get cost forecast › query Parameters

workspaceId

string · required

months

integer · int32

Default: 3

Get cost forecast › Responses

Success

CostForecastResponse

isAvailable

boolean · required

ForecastMonthResponse[] · required

CurrencyAmount[] · required

currentMonthActual

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

currentMonthForecast

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

method

string | null

currency

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

confidencePercent

number | null · double

generatedAt

string | null · date-time

Get cost summary

GET

https://api.costfluent.com

/v1/costs/summary

Bearer (API token)

Returns aggregated cost summary with comparisons. A service's percentage is its share of the window's total cost; with conversion off over several currencies, of the total in its own currency.

Needs a token with viewCosts; a workspace token lists its own workspace only.

Get cost summary › query Parameters

startDate

string · date · required

endDate

string · date · required

workspaceId

cloudAccountIds

array | null · style: form · explode: true

filter

string | null

includeCredits

boolean

Default: false

includeRefunds

boolean

Default: true

includeTax

boolean

Default: true

amortize

boolean

Default: true

Get cost summary › Responses

Success

CostSummaryResponse

CurrencyPresentation · required

commitmentDiscounts

CommitmentDiscountPlacement · required

ServiceCostBreakdown[] · required

ProviderCostBreakdown[] · required

totalCost

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

totalListCost

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

totalAmortizedCost

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

currency

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

costChange

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

costChangePercent

number | null · double

historyFloor

string | null · date

dataThrough

string | null · date

comparedThrough

string | null · date

GET/v1/costs/summary

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

Example Responses

{
  "totalCost": "totalCost",
  "totalListCost": "totalListCost",
  "totalAmortizedCost": "totalAmortizedCost",
  "currency": "currency",
  "costChange": "costChange",
  "costChangePercent": 0,
  "presentation": {
    "conversions": [
      {
        "sourceCurrency": "sourceCurrency",
        "sourceAmount": "sourceAmount",
        "convertedAmount": "convertedAmount",
        "method": "method",
        "source": "source",
        "description": "description"
      }
    ],
    "unconverted": [
      {
        "currency": "currency",
        "amount": "amount"
      }
    ],
    "totalsByCurrency": [
      {
        "currency": "currency",
        "amount": "amount"
      }
    ]
  },
  "commitmentDiscounts": "commitmentDiscounts",
  "topServices": [
    {
      "serviceName": "serviceName",
      "cost": "cost",
      "percentage": 0
    }
  ],
  "byProvider": [
    {
      "providerId": "providerId",
      "providerName": "providerName",
      "providerKey": "providerKey",
      "currency": "currency",
      "cost": "cost"
    }
  ],
  "historyFloor": "2024-08-25",
  "dataThrough": "2024-08-25",
  "comparedThrough": "2024-08-25"
}

json

application/json

Cost Alerts Cost estimates