Query cost data via the Cost V2 API - Container Service for Kubernetes

Query real-time estimated costs for cluster workloads through the Cost V2 API with flexible time windows and filters by pod, namespace, label, controller name, or controller kind for real-time cost trend analysis.

Prerequisites

Complete the setup in Overview of obtaining cost data using APIs.

API reference

Request syntax

GET /v2/cost

Request parameters

Parameter	Type	Required	Description
`window`	string	Yes	Time range to query. Supported formats: `today` — the current day `yesterday` — the previous day `week` — the current week `lastweek` — the previous week `month` — the current month `lastmonth` — the previous month Duration: `30m` (last 30 minutes), `12h` (last 12 hours), `7d` (last 7 days) RFC3339 date range: `2024-03-26T00:00:00Z,2024-03-27T00:00:00Z` Unix timestamp range (seconds): `1711382400,1711468800`
`filter`	string	No	Filter by resource category: `namespace`, `controllerName` (e.g., `csi-plugin`), `controllerKind` (e.g., `DaemonSet`, `ReplicaSet`, `Job`), `pod`, `label` (e.g., `[app]:"nginx"`). Separate multiple values with commas: `namespace:"default","kube-system"`. Combine categories with +: `namespace:"default"+label[app]:"nginx"`.
`step`	string	No	Time interval to split results into multiple cost sets (e.g., `1d` or `1w` ). If omitted, the entire `window` returns as one cost set. Note A cost set contains cost data for a Kubernetes object (such as a pod) over a specific time period.
`aggregate`	string	No	Aggregation dimension. Supported values: `namespace` — across all cluster namespaces `controller` — by individual controller `controllerKind` — by controller type (e.g., DaemonSet, ReplicaSet) `label:<name>` — by label key `node` — by compute node
`idle`	boolean	No	Specifies whether to include idle costs. Default: `true`.
`shareIdle`	boolean	No	Specifies whether to distribute idle costs across non-idle allocations. Default: `false`.
`shareSplit`	string	No	Policy for allocating idle costs. Valid values: `weighted` (default) `even`
`idleByNode`	boolean	No	Specifies whether to aggregate idle costs at the node level before distribution. Applies only when `aggregate=node` and `shareIdle=false`. Default: `false`.
`format`	string	No	Output format. Valid values: `json` (default), `csv`.

Response parameters

Parameter	Type	Description
`properties`	object	Kubernetes object properties.
`pod`	string	Pod name.
`node`	string	Node name.
`namespace`	string	Namespace.
`controllerKind`	string	Controller type (e.g., DaemonSet, ReplicaSet).
`controller`	string	Controller name.
`providerID`	string	ECS instance ID for the node.
`labels`	map[string]string	Pod labels. Note Prometheus supports only underscores (`_`) in label names. Hyphens (`-`) and periods (`.`) are converted to underscores.
`start`	string	Start time of the cost set.
`end`	string	End time of the cost set.
`cpuCoreRequestAverage`	float	Average CPU cores requested over the period.
`cpuCoreUsageAverage`	float	Average CPU cores used over the period.
`ramByteRequestAverage`	float	Average memory requested over the period, in bytes.
`ramByteUsageAverage`	float	Average memory used over the period, in bytes.
`cost`	float	Estimated cost for the period. Default: 100% CPU weight. See Cost estimation policies to customize.
`costRatio`	float	Fraction of total cluster cost (`resource cost / total cluster cost`).
`customCost`	float	Cost from a custom estimation policy.

(Optional) Step 1: Customize resource cost weights

The Cost V2 API defaults to 100% CPU weight ({"cpu": "1.0", "memory": "0.0"}). For mixed CPU-memory weighting, update the ack-alibaba-cloud-metrics-adapter Helm chart.

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Applications > Helm.
On the Helm page, find ack-alibaba-cloud-metrics-adapter and click Update in the Actions column.
In the YAML file, update the AlibabaCloudMetricsAdapter.costWeights parameter, then click OK.
See Cost estimation policies.

Step 2: Query cost data

All examples use curl with client certificate authentication. For setup, see Use the Kubernetes API.

Example 1: Query yesterday's DaemonSet costs

Filters by namespace, controller type, and label to return per-pod cost data for yesterday.

Request

curl -G -k --cert ./client-cert.pem --key ./client-key.pem \
  -d 'window=yesterday' \
  -d 'filter=namespace:"kube-system"+controllerKind:"DaemonSet"+label[app]:"terway-eniip"' \
  "$APISERVER/api/v1/namespaces/kube-system/services/ack-metrics-adapter-api-service:8080/proxy/v2/cost" | jq .

Sample response

View the sample response

{
  "data": [
    {
      "kube-system/terway-eniip-88286": {
        "name": "kube-system/terway-eniip-88286",
        "properties": {
          "controller": "terway-eniip",
          "controllerKind": "DaemonSet",
          "namespace": "kube-system",
          "pod": "terway-eniip-88286"
        },
        "start": "2024-03-25T00:00:00+08:00",
        "end": "2024-03-26T00:00:00+08:00",
        "cpuCoreRequestAverage": 0.35,
        "cpuCoreUsageAverage": 0.001,
        "ramByteRequestAverage": 209715200,
        "ramByteUsageAverage": 65815511.04,
        "cost": 1.622,
        "costRatio": 0.016,
        "customCost": 0.972
      },
      "kube-system/terway-eniip-fqxk8": {
        "name": "kube-system/terway-eniip-fqxk8",
        "properties": {
          "controller": "terway-eniip",
          "controllerKind": "DaemonSet",
          "namespace": "kube-system",
          "pod": "terway-eniip-fqxk8"
        },
        "start": "2024-03-25T00:00:00+08:00",
        "end": "2024-03-26T00:00:00+08:00",
        "cpuCoreRequestAverage": 0.35,
        "cpuCoreUsageAverage": 0.001,
        "ramByteRequestAverage": 209715200,
        "ramByteUsageAverage": 72787722.24,
        "cost": 1.622,
        "costRatio": 0.016,
        "customCost": 0.972
      },
      "kube-system/terway-eniip-xjsr8": {
        "name": "kube-system/terway-eniip-xjsr8",
        "properties": {
          "controller": "terway-eniip",
          "controllerKind": "DaemonSet",
          "namespace": "kube-system",
          "pod": "terway-eniip-xjsr8"
        },
        "start": "2024-03-25T00:00:00+08:00",
        "end": "2024-03-26T00:00:00+08:00",
        "cpuCoreRequestAverage": 0.35,
        "cpuCoreUsageAverage": 0.001,
        "ramByteRequestAverage": 209715200,
        "ramByteUsageAverage": 53661380.923,
        "cost": 0.843,
        "costRatio": 0.008,
        "customCost": 0.505
      }
    }
  ]
}

Example 2: Query hourly pod costs over a 3-hour window

Uses step=1h to split a 3-hour window into three hourly cost sets.

Request

curl -G -k --cert ./client-cert.pem --key ./client-key.pem \
  -d 'window=2024-03-24T00:00:00Z,2024-03-24T03:00:00Z' \
  -d 'step=1h' \
  -d 'filter=namespace:"kube-system"+pod:"terway-eniip-kz68n"' \
  "$APISERVER/api/v1/namespaces/kube-system/services/ack-metrics-adapter-api-service:8080/proxy/v2/cost" | jq .

Sample response

View the sample response

{
  "data": [
    {
      "kube-system/terway-eniip-kz68n": {
        "name": "kube-system/terway-eniip-kz68n",
        "properties": {
          "controller": "terway-eniip",
          "controllerKind": "DaemonSet",
          "namespace": "kube-system",
          "pod": "terway-eniip-kz68n"
        },
        "start": "2024-03-24T00:00:00Z",
        "end": "2024-03-24T01:00:00Z",
        "cpuCoreRequestAverage": 0.35,
        "cpuCoreUsageAverage": 0.001,
        "ramByteRequestAverage": 209715200,
        "ramByteUsageAverage": 63583378.285,
        "cost": 0.075,
        "costRatio": 0.025,
        "customCost": 0.045
      }
    },
    {
      "kube-system/terway-eniip-kz68n": {
        "name": "kube-system/terway-eniip-kz68n",
        "properties": {
          "controller": "terway-eniip",
          "controllerKind": "DaemonSet",
          "namespace": "kube-system",
          "pod": "terway-eniip-kz68n"
        },
        "start": "2024-03-24T01:00:00Z",
        "end": "2024-03-24T02:00:00Z",
        "cpuCoreRequestAverage": 0.35,
        "cpuCoreUsageAverage": 0.001,
        "ramByteRequestAverage": 209715200,
        "ramByteUsageAverage": 63111168,
        "cost": 0.075,
        "costRatio": 0.025,
        "customCost": 0.045
      }
    },
    {
      "kube-system/terway-eniip-kz68n": {
        "name": "kube-system/terway-eniip-kz68n",
        "properties": {
          "controller": "terway-eniip",
          "controllerKind": "DaemonSet",
          "namespace": "kube-system",
          "pod": "terway-eniip-kz68n"
        },
        "start": "2024-03-24T02:00:00Z",
        "end": "2024-03-24T03:00:00Z",
        "cpuCoreRequestAverage": 0.35,
        "cpuCoreUsageAverage": 0.001,
        "ramByteRequestAverage": 209715200,
        "ramByteUsageAverage": 63430656,
        "cost": 0.075,
        "costRatio": 0.025,
        "customCost": 0.045
      }
    }
  ]
}

Example 3: Query costs aggregated by the `app` label

Uses aggregate=label:app to group costs by the app label.

Request

curl -G -k --cert ./client-cert.pem --key ./client-key.pem \
  -d 'window=2h' \
  -d 'aggregate=label:app' \
  "$APISERVER/api/v1/namespaces/kube-system/services/ack-metrics-adapter-api-service:8080/proxy/v2/cost" | jq .

Sample response

View the sample response

{
  "data": [
    {
      "__idle__": {
        "name": "__idle__",
        "start": "2024-12-17T09:50:30+08:00",
        "end": "2024-12-17T11:50:30+08:00",
        "cpuCoreRequestAverage": 0,
        "cpuCoreUsageAverage": 0,
        "ramByteRequestAverage": 0,
        "ramByteUsageAverage": 0,
        "cost": 3.8230000000000004,
        "costRatio": 0.6371666666666664,
        "customCost": 0
      },
      "__unallocated__": {
        "name": "__unallocated__",
        "start": "2024-12-17T09:50:30+08:00",
        "end": "2024-12-17T11:50:30+08:00",
        "cpuCoreRequestAverage": 1.135,
        "cpuCoreUsageAverage": 0.024,
        "ramByteRequestAverage": 1901068288,
        "ramByteUsageAverage": 646283264,
        "cost": 0.6000000000000001,
        "costRatio": 0.09999999999999999,
        "customCost": 0
      },
      "ack-alibaba-cloud-metrics-adapter": {
        "name": "ack-alibaba-cloud-metrics-adapter",
        "start": "2024-12-17T09:50:30+08:00",
        "end": "2024-12-17T11:50:30+08:00",
        "cpuCoreRequestAverage": 0.24,
        "cpuCoreUsageAverage": 0.004,
        "ramByteRequestAverage": 482344960,
        "ramByteUsageAverage": 96964608,
        "cost": 0.064,
        "costRatio": 0.010666666666666666,
        "customCost": 0
      },
      "terway-eniip": {
        "name": "terway-eniip",
        "start": "2024-12-17T09:50:30+08:00",
        "end": "2024-12-17T11:50:30+08:00",
        "cpuCoreRequestAverage": 1.0499999999999998,
        "cpuCoreUsageAverage": 0.001,
        "ramByteRequestAverage": 629145600,
        "ramByteUsageAverage": 122054656,
        "cost": 0.5609999999999999,
        "costRatio": 0.0935,
        "customCost": 0
      }
    }
  ]
}

Next steps

The Allocation API combines bill and cluster cost data for amortized cost reconciliation. See Obtain data using the Allocation API.

Prerequisites

API reference

Request syntax

Request parameters

Response parameters

(Optional) Step 1: Customize resource cost weights

Step 2: Query cost data

Example 1: Query yesterday's DaemonSet costs

Example 2: Query hourly pod costs over a 3-hour window

Example 3: Query costs aggregated by the app label

Next steps

Example 3: Query costs aggregated by the `app` label