Cost Modes

cost_mode takes two values, fully_loaded (the default) and workload_only. Any other value returns 422 INVALID_COST_MODE. For what each mode measures and when to use it, see Cost modes. This page covers how the API handles the parameter.

Where the parameter goes

On GET endpoints, cost_mode is a query parameter:

curl -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://public-api.kubeadapt.io/v1/workloads?cost_mode=workload_only"

On POST /v1/cost-explorer/query, it is a field in the JSON body. A ?cost_mode= query parameter on that route is ignored.

Both values are lowercase and underscore-separated: fully-loaded or workload-only return 422 INVALID_COST_MODE. When the parameter is absent on an accepting endpoint, the response uses fully_loaded, except the namespace and workload cost trends, which default to workload_only.

The rejection matrix

On namespaces, workloads and pods, fully_loaded includes the resource's share of idle capacity and cluster overhead, and workload_only does not. Team and department run rate is the weighted cost of the assigned workloads over the last seven complete days (UTC), per hour, at the requested mode.

The echo contract

On endpoints that accept ?cost_mode=, the mode is echoed in two places:

1{
2  "data": {
3    "id": "b9f1a342-7c5e-4d8a-9e2b-1234567890ab",
4    "kind": "Workload",
5    "metadata": { "name": "api-gateway", "namespace": "checkout" },
6    "cost": {
7      "current_run_rate_hourly": { "amount": "12.4800", "currency": "USD" },
8      "cost_mode": "fully_loaded",
9      "last_updated_at": "2026-05-21T10:29:00Z"
10    }
11  },
12  "meta": {
13    "request_id": "0196f1c2-7a3e-7b5d-9c41-2e8f6a1d3b74",
14    "applied_at": "2026-05-21T10:30:00Z",
15    "cost_mode": "fully_loaded",
16    "basis": "legacy"
17  }
18}

Both fields are equal on a single response. On rejecting endpoints neither appears: a cluster object has no cost.cost_mode, and the cluster list's meta has no cost_mode. Cost Explorer responses have no meta block; the mode you sent is the mode applied.

What 422 looks like

Sending ?cost_mode= to a rejecting endpoint:

curl -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://public-api.kubeadapt.io/v1/clusters?cost_mode=workload_only"

1{
2  "data": null,
3  "meta": {
4    "request_id": "0196f1c2-7a3e-7b5d-9c41-2e8f6a1d3b75",
5    "applied_at": "2026-05-21T10:30:00Z"
6  },
7  "error": {
8    "code": "INVALID_COST_MODE",
9    "message": "cost_mode is not supported on this endpoint",
10    "details": [
11      { "field": "cost_mode", "reason": "not_supported_on_this_endpoint" }
12    ]
13  }
14}

Sending an unknown value to an accepting endpoint:

curl -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://public-api.kubeadapt.io/v1/workloads?cost_mode=fully-loaded"

1{
2  "data": null,
3  "meta": {
4    "request_id": "0196f1c2-7a3e-7b5d-9c41-2e8f6a1d3b76",
5    "applied_at": "2026-05-21T10:30:00Z"
6  },
7  "error": {
8    "code": "INVALID_COST_MODE",
9    "message": "cost_mode must be one of: fully_loaded, workload_only",
10    "details": [
11      { "field": "cost_mode", "allowed": ["fully_loaded", "workload_only"] }
12    ]
13  }
14}

Both use the same code. The first carries reason: "not_supported_on_this_endpoint"; the second carries the allowed list instead.

Cost basis

basis is a second, independent parameter on every cost endpoint. It chooses which cost components are summed into each total:

Pass it as ?basis=legacy|all on GET endpoints, or as basis in the Cost Explorer body (or ?basis= on that route; if both are given they must match). An unknown value returns 422 VALIDATION_ERROR with details[0].allowed. /v1/teams/{id}/assignments carries no cost and answers any basis the same way. The requested basis is echoed on meta.basis, and each cost block states the basis it was summed at.

Current run-rate figures (current_run_rate_hourly on clusters, namespaces, workloads, nodes, teams and the organization snapshot) cannot include network or external costs. With ?basis=all they return the legacy figure with partial: true. The FOCUS export always carries every component, so it accepts only basis=all.

See also

• Cost modes, what fully_loaded and workload_only measure and when to use each.
• API Overview, the envelope and the cost block fields.
• Error Handling, the INVALID_COST_MODE code and the details payload shapes.
• Organization, the snapshot that rejects cost_mode and the dashboard that accepts it.