All Products
Search

This Product

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

    Document Center

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

    Last Updated:Mar 26, 2026

    The Cost V2 API (GET /v2/cost) returns real-time estimated costs for your cluster workloads. Filter by pod, namespace, label, controller name, or controller type, and aggregate results by any of those dimensions for cost trend analysis and internal reporting.

    Prerequisites

    Before you begin, complete the setup described 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: <br>- today — the current day <br>- yesterday — the previous day <br>- week — the current week <br>- lastweek — the previous week <br>- month — the current month <br>- lastmonth — the previous month <br>- Duration: 30m (last 30 minutes), 12h (last 12 hours), 7d (last 7 days) <br>- RFC3339 date range: 2024-03-26T00:00:00Z,2024-03-27T00:00:00Z <br>- Unix timestamp range (seconds): 1711382400,1711468800
    filter string No Filter results by resource category. Supported categories: namespace, controllerName (e.g., csi-plugin), controllerKind (e.g., DaemonSet, ReplicaSet, Job), pod, label (e.g., [app]:"nginx"). <br><br>To filter by multiple values in the same category, separate values with a comma: namespace:"default","kube-system". <br><br>To combine different categories, use a plus sign: namespace:"default"+label[app]:"nginx".
    step string No Time interval for splitting the response into multiple cost sets (e.g., 1d or 1w). If not specified, the entire window is returned as a single cost set. <br>
    Note

    A cost set contains cost data for a Kubernetes object (such as a pod) over a specific time period.
    aggregate string No Dimension to aggregate results by. Supported values: <br>- namespace — aggregates across all namespaces in the cluster <br>- controller — aggregates by individual controllers <br>- controllerKind — aggregates by controller type (e.g., DaemonSet, ReplicaSet) <br>- label:<name> — aggregates by a specific label key <br>- node — aggregates by compute node
    idle boolean No Specifies whether to include idle costs in the response. 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: <br>- weighted (default) <br>- 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 Properties of the associated Kubernetes object.
    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 ID of the Elastic Compute Service (ECS) instance that corresponds to 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. The default cost estimation policy uses a 100% CPU weight. To customize resource weights, see Cost estimation policies.
    costRatio float This resource's cost as a fraction of total cluster cost (resource cost / total cluster cost).
    customCost float Cost calculated using a custom cost estimation policy.

    (Optional) Step 1: Customize resource cost weights

    By default, the Cost V2 API calculates costs using a 100% CPU weight ({"cpu": "1.0", "memory": "0.0"}). To use a mixed CPU and memory weighting, update the ack-alibaba-cloud-metrics-adapter Helm chart.

    1. Log on to the ACK console. In the left navigation pane, click ACK consoleClusters.

    2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Applications > Helm.

    3. On the Helm page, find ack-alibaba-cloud-metrics-adapter and click Update in the Actions column.

    4. In the YAML file, update the AlibabaCloudMetricsAdapter.costWeights parameter, then click OK.

      image

      For details on mixed-resource cost estimation, see Cost estimation policies.

    Step 2: Query cost data

    All examples use curl to access the Kubernetes API via client certificate authentication. For setup instructions, 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 separate cost sets, each covering one hour.

    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 value.

    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
      }
    }
  ]
}

    What's next

    The Allocation API combines bill data with cluster cost data to provide amortized costs for reconciliation. See Obtain data using the Allocation API.