The Allocation API retrieves cost allocation information for any Kubernetes concept, such as cost by namespace, label, deployment, service, and more. It is directly integrated with the Kubecost ETL caching layer and CSV pipeline so it can scale for large clusters.
openapi: 3.1.0
info:
title: Kubecost Allocation API
description: >-
The Allocation API retrieves cost allocation information for any Kubernetes
concept, such as cost by namespace, label, deployment, service, and more.
It is directly integrated with the Kubecost ETL caching layer and CSV
pipeline so it can scale for large clusters.
version: 2.0.0
contact:
name: Kubecost
url: https://docs.kubecost.com/apis/monitoring-apis/api-allocation
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://{kubecost-address}
description: Kubecost self-hosted instance
variables:
kubecost-address:
default: localhost:9090
description: Address of the Kubecost instance
paths:
/model/allocation:
get:
operationId: getAllocation
summary: Kubecost Query allocation cost data
description: >-
Retrieves cost allocation data for Kubernetes workloads, aggregated by
the specified field over the given time window.
parameters:
- name: window
in: query
required: true
description: >-
Duration of time over which to query. Accepts units of time
(e.g. 3d, 24h, 7d), relative time (e.g. yesterday, lastweek,
lastmonth), or RFC3339 date pairs.
schema:
type: string
examples:
days:
value: "3d"
summary: Last 3 days
relative:
value: "lastweek"
summary: Last week
- name: aggregate
in: query
required: false
description: >-
Field by which to aggregate results. Supported values include
cluster, namespace, controllerKind, controller, service,
deployment, statefulset, daemonset, job, label, annotation, pod,
and container. Supports multi-aggregation via comma-separated
values.
schema:
type: string
examples:
namespace:
value: namespace
multi:
value: namespace,label:app
- name: step
in: query
required: false
description: >-
Duration of a single allocation set. If unspecified, this defaults
to the window, so that you receive exactly one set for the entire
window.
schema:
type: string
- name: accumulate
in: query
required: false
description: >-
If true, sum the entire range of sets into a single set.
schema:
type: boolean
default: false
- name: idle
in: query
required: false
description: >-
Whether to return idle cost. If true, idle allocations are returned.
schema:
type: boolean
default: true
- name: external
in: query
required: false
description: >-
Whether to include external (out-of-cluster) costs.
schema:
type: boolean
default: false
- name: filterClusters
in: query
required: false
description: Filter results by cluster name (comma-separated).
schema:
type: string
- name: filterNamespaces
in: query
required: false
description: Filter results by namespace (comma-separated).
schema:
type: string
- name: filterControllerKinds
in: query
required: false
description: Filter results by controller kind (comma-separated).
schema:
type: string
- name: filterControllers
in: query
required: false
description: Filter results by controller name (comma-separated).
schema:
type: string
- name: filterLabels
in: query
required: false
description: >-
Filter results by label in the format label:value
(comma-separated).
schema:
type: string
- name: filterAnnotations
in: query
required: false
description: >-
Filter results by annotation in the format annotation:value
(comma-separated).
schema:
type: string
- name: filterServices
in: query
required: false
description: Filter results by service (comma-separated).
schema:
type: string
- name: shareIdle
in: query
required: false
description: >-
If true, idle cost is allocated proportionally across tenants.
schema:
type: boolean
default: false
- name: splitIdle
in: query
required: false
description: >-
If true, idle cost is split into separate allocations by cluster
and node.
schema:
type: boolean
default: false
- name: idleByNode
in: query
required: false
description: >-
If true, idle allocations are created on a per-node basis.
schema:
type: boolean
default: false
- name: format
in: query
required: false
description: Output format. Supports csv and json.
schema:
type: string
enum:
- json
- csv
default: json
responses:
"200":
description: Successful allocation query response.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
data:
type: array
items:
type: object
additionalProperties:
$ref: "#/components/schemas/Allocation"
"400":
description: Invalid request parameters.
tags:
- Model
/model/allocation/totals:
get:
operationId: getAllocationTotals
summary: Kubecost Query total allocation costs
description: >-
Returns a single total cost value for the given window, without
individual allocations breakdown.
parameters:
- name: window
in: query
required: true
description: Duration of time over which to query.
schema:
type: string
- name: aggregate
in: query
required: false
description: Field by which to aggregate results.
schema:
type: string
- name: filterClusters
in: query
required: false
schema:
type: string
- name: filterNamespaces
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful total allocation query response.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
data:
type: array
items:
type: object
additionalProperties:
$ref: "#/components/schemas/Allocation"
tags:
- Model
components:
schemas:
Allocation:
type: object
properties:
name:
type: string
description: Name of the allocation.
properties:
type: object
properties:
cluster:
type: string
node:
type: string
namespace:
type: string
controller:
type: string
controllerKind:
type: string
pod:
type: string
container:
type: string
labels:
type: object
additionalProperties:
type: string
annotations:
type: object
additionalProperties:
type: string
services:
type: array
items:
type: string
window:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
start:
type: string
format: date-time
end:
type: string
format: date-time
cpuCores:
type: number
cpuCoreRequestAverage:
type: number
cpuCoreUsageAverage:
type: number
cpuCoreHours:
type: number
cpuCost:
type: number
cpuCostAdjustment:
type: number
cpuEfficiency:
type: number
gpuCount:
type: number
gpuHours:
type: number
gpuCost:
type: number
gpuCostAdjustment:
type: number
networkTransferBytes:
type: number
networkReceiveBytes:
type: number
networkCost:
type: number
networkCostAdjustment:
type: number
loadBalancerCost:
type: number
loadBalancerCostAdjustment:
type: number
pvBytes:
type: number
pvByteHours:
type: number
pvCost:
type: number
pvCostAdjustment:
type: number
ramBytes:
type: number
ramByteRequestAverage:
type: number
ramByteUsageAverage:
type: number
ramByteHours:
type: number
ramCost:
type: number
ramCostAdjustment:
type: number
ramEfficiency:
type: number
externalCost:
type: number
sharedCost:
type: number
totalCost:
type: number
totalEfficiency:
type: number
tags:
- name: Model