Cloud Cost API

The Cloud Cost API provides multiple endpoints to obtain accurate cost information from your cloud service providers (CSPs), including data available from cloud billing reports (such as AWS' Cost and Usage Report (CUR)).

Cloud Cost querying API

GET http://<your-kubecost-address>/model/cloudCost

Samples full granularity of cloud costs from cloud billing report (ex. AWS' Cost and Usage Report)

Path Parameters

NameTypeDescription

window*

String

Duration of time over which to query. Accepts multiple different formats of time (see this Using the window parameter section for more info).

costMetric

String

Determines which cloud cost metric type will be returned. Acceptable values are AmortizedNetCost, InvoicedCost, ListCost, and NetCost. Default is AmortizedNetCost.

aggregate

String

Field by which to aggregate the results. Accepts: invoiceEntityID, accountID, provider, service, and label:<name>. Supports multi-aggregation using comma-separated lists. Example: aggregate=accountID,service

accumulate

boolean

When set to false, this endpoint returns daily time series data vs cumulative data. Default value is false.

offset

int

Refers to the number of line items you are offsetting. Pairs with limit. See the section on Using offset and limit parameters to parse payload results for more info.

limit

int

Refers to the number of line items per page. Pair with the offset parameter to filter your payload to specific pages of line items. You should also set accumulate=true to obtain a single list of line items, otherwise you will receive a group of line items per interval of time being sampled.

filterInvoiceEntityIDs

String

Filter for account

filterAccountIDs

String

GCP only, filter for projectID

filterProviders

String

Filter for cloud service provider

filterProvidersID

String

Filter for resource-level ID given by CSP

filterServices

String

Filter for cloud service

filterCategories

String

Filter based on object type

filterLabels

String

Filter for a specific label. Does not support filtering for multiple labels at once.

{
    "code": 200,
    "data": {
        "graphData": [
            {
                "start": "",
                "end": "",
                "items": []
            }
        ],
        "tableTotal": {
            "name": "",
            "kubernetesPercent": 0,
            "cost": 0
        },
        "tableRows": []
    }
}

Using the CostMetric parameter

CostMetric values are based on and calculated following standard FinOps dimensions and metrics. The four available metrics supported by the Cloud Cost API are:

CostMetric valueDescription

NetCost

Costs inclusive of discounts and credits. Will also include one-time and recurring charges.

AmortizedNetCost

NetCost with removed cash upfront fees and amortized

ListCost

CSP pricing without any discounts

InvoicedCost

Pricing based on usage during billing period

Providing a value for CostMetric is optional, but it will default to AmortizedNetCost if not otherwise provided.

See our Cloud Cost Metrics doc to learn more about these cost metric types and how they are calculated.

Understanding kubernetesPercent

Each CostMetric also has a kubernetesPercent value. Unaggregated, this value will be 0 or 1. When you aggregate, kubernetesPercent is determined by multiplying the costMetric cost by its kubernetesPercent and aggregating that value as kubernetesCost for that costMetric. That kubernetesCost is then divided by the aggregated total costs to determine the new kubernetesPercent. Since this process results in unique values for each costMetric, this value is included as part of the cost metric.

Examples

Query for cloud net costs within the past two days, aggregated by accounts, filtered only for Amazon EC2 costs

http:/<your-kubecost-address>/model/cloudCost?window=2d&filterServices=AmazonEC2&aggregate=invoiceEntityID

Last updated