Cost Reports

Download schema

List cost reports

GET

https://api.costfluent.com

/v1/cost-reports

Bearer (API token)

Returns all cost reports for a workspace, optionally filtered by folder.

Needs a token with viewCostReports on the workspace.

List cost reports › query Parameters

workspaceId

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

folderId

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 reports › Responses

Success

PaginatedResponseOfCostReportResponse

PaginationLinks · required

CostReportResponse[] · required

GET/v1/cost-reports

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

Example Responses

{
  "links": {
    "self": "self",
    "first": "first",
    "prev": "prev",
    "next": "next",
    "last": "last"
  },
  "data": [
    {
      "id": "id",
      "title": "title",
      "folderId": "string",
      "filter": "filter",
      "groupBy": [
        {
          "dimension": "dimension",
          "key": "key"
        }
      ],
      "dateInterval": "dateInterval",
      "startDate": "2024-08-25",
      "endDate": "2024-08-25",
      "chartType": "chartType",
      "chartAxis": "chartAxis",
      "dateBin": "dateBin",
      "settings": {
        "includeCredits": true,
        "includeRefunds": true,
        "includeTax": true,
        "amortize": true,
        "showForecast": true,
        "compareToLastPeriod": true,
        "comparisonStartDate": "2024-08-25",
        "comparisonEndDate": "2024-08-25",
        "measure": "measure",
        "unitCostMetricId": "string",
        "unitCostLabelFilter": [
          {
            "key": "key",
            "values": [
              "string"
            ]
          }
        ],
        "unitCostCalculation": "unitCostCalculation",
        "unitCostScale": 0
      },
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z",
      "isDefault": true
    }
  ]
}

json

application/json

Create cost report

POST

https://api.costfluent.com

/v1/cost-reports

Bearer (API token)

Creates a new cost report configuration.

Needs a token with createCostReport on the workspace.

Create cost report › 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 cost report › Request Body

CreateCostReportRequest

workspaceId

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

title

string · minLength: 0 · maxLength: 200 · required

filter

string | null

array | null

startDate

string | null · date

endDate

string | null · date

chartType

ChartType · enum

Enum values:

line

bar

stackedBar

area

pie

table

Create cost report › Responses

Created

CostReportCreatedResponse

id

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

title

string · required

POST/v1/cost-reports

curl https://api.costfluent.com/v1/cost-reports \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "title": "title",
  "folderId": "string",
  "filter": "filter",
  "groupBy": [
    {
      "dimension": "provider",
      "key": "key"
    }
  ],
  "dateInterval": "string",
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "chartType": "line",
  "chartAxis": "date",
  "dateBin": "string",
  "settings": {
    "includeCredits": true,
    "includeRefunds": true,
    "includeTax": true,
    "amortize": true,
    "showForecast": true,
    "compareToLastPeriod": true,
    "comparisonStartDate": "2024-08-25",
    "comparisonEndDate": "2024-08-25",
    "measure": "string",
    "unitCostMetricId": "string",
    "unitCostLabelFilter": [
      {
        "key": "key",
        "values": [
          "string"
        ]
      }
    ],
    "unitCostCalculation": "string",
    "unitCostScale": 0
  }
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "title": "title",
  "folderId": "string",
  "filter": "filter",
  "groupBy": [
    {
      "dimension": "provider",
      "key": "key"
    }
  ],
  "dateInterval": "string",
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "chartType": "line",
  "chartAxis": "date",
  "dateBin": "string",
  "settings": {
    "includeCredits": true,
    "includeRefunds": true,
    "includeTax": true,
    "amortize": true,
    "showForecast": true,
    "compareToLastPeriod": true,
    "comparisonStartDate": "2024-08-25",
    "comparisonEndDate": "2024-08-25",
    "measure": "string",
    "unitCostMetricId": "string",
    "unitCostLabelFilter": [
      {
        "key": "key",
        "values": [
          "string"
        ]
      }
    ],
    "unitCostCalculation": "string",
    "unitCostScale": 0
  }
}

json

Example Responses

{
  "id": "id",
  "title": "title"
}

json

application/json

Get cost report

GET

https://api.costfluent.com

/v1/cost-reports/{costReportId}

Bearer (API token)

Returns a specific cost report configuration.

Needs a token with viewCostReports on the workspace.

Get cost report › path Parameters

costReportId

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

Get cost report › query Parameters

workspaceId

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

Get cost report › Responses

Success

CostReportResponse

id

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

title

string · required

ReportGroupingResponse[] · required

dateInterval

string · required

chartType

string · required

chartAxis

string · required

dateBin

string · required

CostReportSettingsResponse · required

createdAt

string · date-time · required

isDefault

boolean · required

filter

string | null

startDate

string | null · date

endDate

string | null · date

updatedAt

string | null · date-time

GET/v1/cost-reports/{costReportId}

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

Example Responses

{
  "id": "id",
  "title": "title",
  "folderId": "string",
  "filter": "filter",
  "groupBy": [
    {
      "dimension": "dimension",
      "key": "key"
    }
  ],
  "dateInterval": "dateInterval",
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "chartType": "chartType",
  "chartAxis": "chartAxis",
  "dateBin": "dateBin",
  "settings": {
    "includeCredits": true,
    "includeRefunds": true,
    "includeTax": true,
    "amortize": true,
    "showForecast": true,
    "compareToLastPeriod": true,
    "comparisonStartDate": "2024-08-25",
    "comparisonEndDate": "2024-08-25",
    "measure": "measure",
    "unitCostMetricId": "string",
    "unitCostLabelFilter": [
      {
        "key": "key",
        "values": [
          "string"
        ]
      }
    ],
    "unitCostCalculation": "unitCostCalculation",
    "unitCostScale": 0
  },
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "isDefault": true
}

json

application/json

Update cost report

PUT

https://api.costfluent.com

/v1/cost-reports/{costReportId}

Bearer (API token)

Updates a cost report configuration.

Needs a token with updateCostReport on the workspace.

Update cost report › path Parameters

costReportId

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

Update cost report › query Parameters

workspaceId

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

Update cost report › 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 cost report › Request Body

UpdateCostReportRequest

title

string | null

clearFolder

boolean

filter

string | null

clearFilter

boolean

array | null

startDate

string | null · date

clearStartDate

boolean

endDate

string | null · date

clearEndDate

boolean

Update cost report › Responses

Success

CostReportResponse

id

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

title

string · required

ReportGroupingResponse[] · required

dateInterval

string · required

chartType

string · required

chartAxis

string · required

dateBin

string · required

CostReportSettingsResponse · required

createdAt

string · date-time · required

isDefault

boolean · required

filter

string | null

startDate

string | null · date

endDate

string | null · date

updatedAt

string | null · date-time

PUT/v1/cost-reports/{costReportId}

curl 'https://api.costfluent.com/v1/cost-reports/:costReportId?workspaceId=<string>' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "title": "title",
  "folderId": "string",
  "clearFolder": true,
  "filter": "filter",
  "clearFilter": true,
  "groupBy": [
    {
      "dimension": "provider",
      "key": "key"
    }
  ],
  "dateInterval": "string",
  "startDate": "2024-08-25",
  "clearStartDate": true,
  "endDate": "2024-08-25",
  "clearEndDate": true,
  "chartType": "line",
  "chartAxis": "date",
  "dateBin": "string",
  "settings": {
    "includeCredits": true,
    "includeRefunds": true,
    "includeTax": true,
    "amortize": true,
    "showForecast": true,
    "compareToLastPeriod": true,
    "comparisonStartDate": "2024-08-25",
    "comparisonEndDate": "2024-08-25",
    "measure": "string",
    "unitCostMetricId": "string",
    "unitCostLabelFilter": [
      {
        "key": "key",
        "values": [
          "string"
        ]
      }
    ],
    "unitCostCalculation": "string",
    "unitCostScale": 0
  }
}'

Example Request Body

{
  "title": "title",
  "folderId": "string",
  "clearFolder": true,
  "filter": "filter",
  "clearFilter": true,
  "groupBy": [
    {
      "dimension": "provider",
      "key": "key"
    }
  ],
  "dateInterval": "string",
  "startDate": "2024-08-25",
  "clearStartDate": true,
  "endDate": "2024-08-25",
  "clearEndDate": true,
  "chartType": "line",
  "chartAxis": "date",
  "dateBin": "string",
  "settings": {
    "includeCredits": true,
    "includeRefunds": true,
    "includeTax": true,
    "amortize": true,
    "showForecast": true,
    "compareToLastPeriod": true,
    "comparisonStartDate": "2024-08-25",
    "comparisonEndDate": "2024-08-25",
    "measure": "string",
    "unitCostMetricId": "string",
    "unitCostLabelFilter": [
      {
        "key": "key",
        "values": [
          "string"
        ]
      }
    ],
    "unitCostCalculation": "string",
    "unitCostScale": 0
  }
}

json

Example Responses

{
  "id": "id",
  "title": "title",
  "folderId": "string",
  "filter": "filter",
  "groupBy": [
    {
      "dimension": "dimension",
      "key": "key"
    }
  ],
  "dateInterval": "dateInterval",
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "chartType": "chartType",
  "chartAxis": "chartAxis",
  "dateBin": "dateBin",
  "settings": {
    "includeCredits": true,
    "includeRefunds": true,
    "includeTax": true,
    "amortize": true,
    "showForecast": true,
    "compareToLastPeriod": true,
    "comparisonStartDate": "2024-08-25",
    "comparisonEndDate": "2024-08-25",
    "measure": "measure",
    "unitCostMetricId": "string",
    "unitCostLabelFilter": [
      {
        "key": "key",
        "values": [
          "string"
        ]
      }
    ],
    "unitCostCalculation": "unitCostCalculation",
    "unitCostScale": 0
  },
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "isDefault": true
}

json

application/json

Delete cost report

DELETE

https://api.costfluent.com

/v1/cost-reports/{costReportId}

Bearer (API token)

Deletes a cost report, removes the dashboard widgets that show it and deactivates its subscriptions. Refused with 409 in_use, naming the budgets, while a budget measures it, and with 422 for the workspace's default report.

Needs a token with deleteCostReport on the workspace.

Delete cost report › path Parameters

costReportId

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

Delete cost report › query Parameters

workspaceId

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

Delete cost report › 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 cost report › Responses

No Content

No data returned

Get cost report data

GET

https://api.costfluent.com

/v1/cost-reports/{costReportId}/data

Bearer (API token)

Returns the computed cost data for a report. A breakdown row's percent 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 on the workspace for every report, and viewCostReports too for a report that charts a business metric.

Get cost report data › path Parameters

costReportId

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

Get cost report data › query Parameters

workspaceId

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

Get cost report data › Responses

Success

CostReportDataResponse

ReportSummaryResponse · required

ReportTimeSeriesResponse[] · required

ReportBreakdownResponse[] · required

startDate

string · date · required

endDate

string · date · required

historyFloor

string | null · date

dataThrough

string | null · date

GET/v1/cost-reports/{costReportId}/data

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

Example Responses

{
  "summary": {
    "totalCost": "totalCost",
    "previousPeriodCost": "previousPeriodCost",
    "changePercent": 0,
    "comparedThrough": "2024-08-25",
    "comparedCost": "comparedCost",
    "previousComparedThrough": "2024-08-25",
    "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"
        }
      ]
    },
    "measure": "measure",
    "totalsByUnit": [
      {
        "unit": "unit",
        "quantity": 0
      }
    ]
  },
  "series": [
    {
      "date": "2024-08-25",
      "groups": [
        {
          "keys": [
            "string"
          ],
          "currency": "currency",
          "isOther": true,
          "cost": "cost",
          "unit": "unit"
        }
      ]
    }
  ],
  "breakdown": [
    {
      "keys": [
        "string"
      ],
      "currency": "currency",
      "isOther": true,
      "cost": "cost",
      "percent": 0,
      "unit": "unit",
      "previousCost": "previousCost",
      "comparedCost": "comparedCost",
      "changePercent": 0
    }
  ],
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "historyFloor": "2024-08-25",
  "comparison": {
    "startDate": "2024-08-25",
    "endDate": "2024-08-25",
    "series": [
      {
        "date": "2024-08-25",
        "previousDate": "2024-08-25",
        "cost": "cost"
      }
    ]
  },
  "forecast": {
    "series": [
      {
        "date": "2024-08-25",
        "amount": "amount",
        "lowerBound": "lowerBound",
        "upperBound": "upperBound"
      }
    ]
  },
  "dataThrough": "2024-08-25",
  "unitCost": {
    "metricId": "metricId",
    "name": "name",
    "unit": "unit",
    "calculation": "calculation",
    "scale": 0,
    "currency": "currency",
    "average": "average",
    "series": [
      {
        "date": "2024-08-25",
        "metricAmount": "metricAmount",
        "unitCost": "unitCost",
        "value": "value"
      }
    ]
  }
}

json

application/json

Cost Filters Custom Provider