API

The OpenCost API provides real-time and historical reporting of Kubernetes cloud costs. The /allocation/compute endpoint is the primary API for OpenCost, accessed via HTTP GET.

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.

Quick Start Example

Here is an example of an OpenCost API query:

$ curl http://localhost:9003/allocation \
  -d window=7d \
  -d aggregate=namespace \
  -d accumulate=false \
  -d resolution=1m
  -G

This is the default query for the OpenCost UI and produces output similar to this. More examples are available on the API Examples page.

Allocation API

The standard OpenCost API query for costs and resources allocated to Kubernetes workloads. You may specify the window date range, the Kubernetes primitive(s) to aggregate on, the step for the duration of returned sets, and the resolution for the duration to use for Prometheus queries.

/allocation/compute

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:name, and annotation:name. Also accepts comma-separated lists for multi-aggregation, like 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.

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