API

The OpenCost API provides real-time and historical reporting of Kubernetes cloud costs based on on-demand list pricing as well as the cloud costs retrieved from cloud providers through their cost and usage reports.

note

Throughout our API documentation, we use localhost:9003 as the default OpenCost API URL, but your OpenCost instance may be exposed by a service or ingress. To reach the OpenCost API at port 9003, run: kubectl -n opencost port-forward deployment/opencost 9003. You may also expose the OpenCost UI on port 9090 with the command kubectl -n opencost port-forward deployment/opencost 9003 9090.

Examples using the API endpoints are provided in the API Examples page.

Allocation API

The standard OpenCost API query for costs and resources allocated to Kubernetes workloads based on on-demand list pricing. You may specify the window date range, the Kubernetes primitive(s) to aggregate on, the step for the duration of returned sets, the resolution for the duration to use for Prometheus queries, and includeIdle for whether to include the __idle__ usage for the cluster.

/allocation

QUERY PARAMETERS

window	string
required	Duration of time over which to query. Accepts: words like today, week, month, yesterday, lastweek, lastmonth; durations like 30m, 12h, 7d; RFC3339 date pairs like 2021-01-02T15:04:05Z,2021-02-02T15:04:05Z; Unix timestamps like 1578002645,1580681045. Examples: window=today - The current day window=month - The month-to-date window=lastweek - The previous week window=30m - The last 30 minutes window=12h - The last 12 hours window=7d - The previous 7 days window=2023-01-18T10:30:00Z,2023-01-19T10:30:00Z - RFC3339 date/time range window=1674073869,1674193869 - Unix timestamp range
aggregate	string
	Field by which to aggregate the results. Accepts: cluster, node, namespace, controllerKind, controller, service, pod, container, label:LABEL_NAME, and annotation:name. Also accepts comma-separated lists for multi-aggregation, like aggregate=namespace,label:app. Examples: aggregate=cluster - Aggregates by the cluster. aggregate=node - Aggregates by the compute nodes in the cluster. aggregate=namespace - Aggregates by the namespaces in the cluster. aggregate=controllerKind - Aggregates by the kinds of controllers present in the cluster. aggregate=controller - Aggregates by the individual controllers within the cluster. aggregate=service - Aggregates by the services within the cluster. aggregate=pod - Aggregates by the individual pods within the cluster. aggregate=container - Aggregates by the containers present in the cluster.
step	string
	Duration of a single allocation set. If unspecified, this defaults to the window, so that you receive exactly one set for the entire window. If specified, it works chronologically backward, querying in durations of step until the full window is covered. Default is window. Examples: step=30m - 30 minute steps over the duration of the window. step=2h - 2 hour steps over the duration of the window step=1d - Daily steps over the duration of the window (ie. lastweek or month
resolution	string
	Duration to use as resolution in Prometheus queries. Smaller values (i.e. higher resolutions) will provide better accuracy, but worse performance (i.e. slower query time, higher memory use). Larger values (i.e. lower resolutions) will perform better, but at the expense of lower accuracy for short-running workloads. Default is 1m. Examples: resolution=1m - Highly accurate, slower query. resolution=30m - Less accurate, faster query. Not recommended for short-lived workloads.
includeIdle	boolean
	Whether to return the calculated idle field for the query. Default is false. Examples: includeIdle=true

Assets API

The Assets API retrieves backing cost data broken down by individual assets in your cluster. It is not yet exposed in the UI.

/assets

QUERY PARAMETERS

window

string

required

Duration of time over which to query. Accepts: words like today, week, month, yesterday, lastweek, lastmonth; durations like 30m, 12h, 7d; RFC3339 date pairs like 2021-01-02T15:04:05Z,2021-02-02T15:04:05Z; Unix timestamps like 1578002645,1580681045. Examples: window=today - The current day window=month - The month-to-date window=lastweek - The previous week window=30m - The last 30 minutes window=12h - The last 12 hours window=7d - The previous 7 days window=2023-01-18T10:30:00Z,2023-01-19T10:30:00Z - RFC3339 date/time range window=1674073869,1674193869 - Unix timestamp range

Cloud Costs API

The Cloud Costs API retrieves cloud cost data from cloud providers by reading cost and usage reports. You will need additional configuration for supporting the billing integration with your cloud provider.

/cloudCost

QUERY PARAMETERS

window	string
required	Duration of time over which to query. Accepts: words like today, week, month, yesterday, lastweek, lastmonth; durations like 30m, 12h, 7d; RFC3339 date pairs like 2021-01-02T15:04:05Z,2021-02-02T15:04:05Z; Unix timestamps like 1578002645,1580681045. Examples: window=today - The current day window=month - The month-to-date window=lastweek - The previous week window=30m - The last 30 minutes window=12h - The last 12 hours window=7d - The previous 7 days window=2023-10-18T10:30:00Z,2023-10-19T10:30:00Z - RFC3339 date/time range window=1674073869,1674193869 - Unix timestamp range
aggregate	string
	Field by which to aggregate the results. Accepts: invoiceEntityID, accountID, provider, providerID, category, and service. Also accepts comma-separated lists for multi-aggregation, like aggregate=provider,service. If no value is provided, the entire list of items is returned. Examples: aggregate=accountID - Aggregates by the Account. aggregate=category - Aggregates by the individual controllers within the cluster. aggregate=invoiceEntityID - Aggregates by the Invoice Entity. aggregate=provider - Aggregates by the Provider. aggregate=providerID - Aggregates by the Provider ID. aggregate=service - Aggregates by the Service.
accumulate	string
	Step size of the accumulation. Accepts: all, hour, day, week, month, and quarter. Default: day Examples:
filter	string
	V2 filter parameter.

External Costs API

customCost/timeseries

Samples of costs of third-party services. Essentially equivalent to calling /total over a range of time steps. For example, querying for the past 7 days will give you a /total response for each of those days, individually. All available aggregations and filters are the same as with /total

QUERY PARAMETERS

window	string
required	Duration of time over which to query. Accepts: words like today, week, month, yesterday, lastweek, lastmonth; durations like 30m, 12h, 7d; RFC3339 date pairs like 2021-01-02T15:04:05Z,2021-02-02T15:04:05Z; Unix timestamps like 1578002645,1580681045. Examples: window=today - The current day window=month - The month-to-date window=lastweek - The previous week window=30m - The last 30 minutes window=12h - The last 12 hours window=7d - The previous 7 days window=2024-05-18T10:30:00Z,2024-05-19T10:30:00Z - RFC3339 date/time range window=1674073869,1674193869 - Unix timestamp range
aggregate	string
	Field by which to aggregate the results. Accepts: invoiceEntityID, accountID, provider, providerID, category, and service. Also accepts comma-separated lists for multi-aggregation, like provider,service. If no value is provided, the entire list of items is returned. Examples: aggregate=accountID - Aggregates by the Account. aggregate=category - Aggregates by the individual controllers within the cluster. aggregate=invoiceEntityID - Aggregates by the Invoice Entity. aggregate=provider - Aggregates by the Provider. aggregate=providerID - Aggregates by the Provider ID. aggregate=service - Aggregates by the Service.
accumulate	string
	Step size of the accumulation. Accepts: all, hour, day, week, month, and quarter. Default: day Examples: accumulate=hour accumulate=day accumulate=week
filter	string
	The available filters are the same as the available aggregations. Accepts: V2 filter parameters. Examples: filter=domain:"datadog" filter=resourceType:"infra_hosts" filter=zone:"us"

customCost/total

Used to retrieve a summary of third-party costs over a window.

window	string
required	Duration of time over which to query. Accepts: words like today, week, month, yesterday, lastweek, lastmonth; durations like 30m, 12h, 7d; RFC3339 date pairs like 2021-01-02T15:04:05Z,2021-02-02T15:04:05Z; Unix timestamps like 1578002645,1580681045. Examples: window=today - The current day window=month - The month-to-date window=lastweek - The previous week window=30m - The last 30 minutes window=12h - The last 12 hours window=7d - The previous 7 days window=2024-05-18T10:30:00Z,2024-05-19T10:30:00Z - RFC3339 date/time range window=1674073869,1674193869 - Unix timestamp range
aggregate	string
	Field by which to aggregate the results. Accepts: invoiceEntityID, accountID, provider, providerID, category, and service. Also accepts comma-separated lists for multi-aggregation, like provider,service. If no value is provided, the entire list of items is returned. Examples: aggregate=accountID - Aggregates by the Account. aggregate=category - Aggregates by the individual controllers within the cluster. aggregate=invoiceEntityID - Aggregates by the Invoice Entity. aggregate=provider - Aggregates by the Provider. aggregate=providerID - Aggregates by the Provider ID. aggregate=service - Aggregates by the Service.
accumulate	string
	Step size of the accumulation. Accepts: all, hour, day, week, month, and quarter. Default: day Examples: accumulate=hour accumulate=day accumulate=week
filter	string
	The available filters are the same as the available aggregations. Accepts: V2 filter parameters. Examples: filter=domain:"datadog" filter=resourceType:"infra_hosts" filter=zone:"us"

OpenAPI Swagger

The source for the OpenCost API is available as an OpenAPI swagger.json. The OpenCost API is available under the Apache 2.0 License.

Theoretical error bounds

Tuning the resolution parameter allows the querier to make tradeoffs between accuracy and performance. For long-running pods (>1d) resolution can be tuned aggressively low (>10m) with relatively little effect on accuracy. However, even modestly low resolutions (5m) can result in significant accuracy degradation for short-running pods (<1h).

Here, we provide theoretical error bounds for different resolution values given pods of differing running durations. The tuple represents lower- and upper-bounds for accuracy as a percentage of the actual value. For example:

• 1.00, 1.00 means that results should always be accurate to less than 0.5% error
• 0.83, 1.00 means that results should never be high by more than 0.5% error, but could be low by as much as 17% error
• -1.00, 10.00 means that the result could be as high as 1000% error (e.g. 30s pod being counted for 5m) or the pod could be missed altogether, i.e. -100% error.

resolution	30s pod	5m pod	1h pod	1d pod	7d pod
1m	-1.00, 2.00	0.80, 1.00	0.98, 1.00	1.00, 1.00	1.00, 1.00
2m	-1.00, 4.00	0.80, 1.20	0.97, 1.00	1.00, 1.00	1.00, 1.00
5m	-1.00, 10.00	-1.00, 1.00	0.92, 1.00	1.00, 1.00	1.00, 1.00
10m	-1.00, 20.00	-1.00, 2.00	0.83, 1.00	0.99, 1.00	1.00, 1.00
30m	-1.00, 60.00	-1.00, 6.00	0.50, 1.00	0.98, 1.00	1.00, 1.00
60m	-1.00, 120.00	-1.00, 12.00	-1.00, 1.00	0.96, 1.00	0.99, 1.00