API Reference

Organization

Tenant-level snapshot plus the month-to-date dashboard. Two endpoints, one for the headline numbers, one for billed cost and top clusters.

Last updated 2026-10-29

Two endpoints cover the tenant-level surface. GET /v1/organization returns the static snapshot: identity, aggregate capacity, utilization counts, and hourly run rate across the clusters the API key can see. GET /v1/organization/dashboard adds the live cost view: month-to-date billed cost, savings potential, and the top clusters ranked by month-to-date cost — and is the only place MTD and savings figures live. Both require the organization:read scope. The snapshot rejects ?cost_mode=; the dashboard accepts it.

Get organization snapshot

GET /v1/organization

Required scope: organization:read

Returns the tenant identity, aggregate capacity, utilization, and counts across every cluster the API key is allowed to see. This is a single-resource response, not a list, so there is no pagination.

Counts of interest live on utilization.counts: clusters is every cluster the API key can see; connected_clusters is the subset whose last agent heartbeat is within the 180-second staleness window. The two differ when an agent has gone quiet. See Clusters for the staleness contract. workloads counts every workload kind, including custom kinds such as Argo Rollout, and equals total_count on /v1/workloads.

cost.current_run_rate_hourly is the clusters' fully loaded cost over the last seven complete days (UTC), per hour. Clusters that have not reported for 15 minutes are left out of it and listed in cost.excluded_cluster_ids ([] when none).

Example request

bash

curl -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://public-api.kubeadapt.io/v1/organization"

Example response

json

1{
2  "data": {
3    "id": "f47a9b21-3c5d-4e6f-8a9b-0c1d2e3f4a5b",
4    "kind": "Organization",
5    "metadata": {
6      "name": "Northwind Holdings",
7      "domain": "northwind.example",
8      "plan_type": "growth",
9      "is_active": true,
10      "created_at": "2025-11-04T09:12:00Z"
11    },
12    "capacity": {
13      "cpu": { "total_cores": 1248.0, "allocatable_cores": 1162.4 },
14      "memory": { "total_bytes": 5497558138880, "allocatable_bytes": 5119018639360 },
15      "gpu": { "total": 24, "allocatable": 24, "model": "NVIDIA A10G" },
16      "storage": { "total_bytes": 107374182400000 }
17    },
18    "utilization": {
19      "cpu": { "requested_cores": 842.7, "used_cores": 612.3, "utilization_percent": 49.1 },
20      "memory": { "requested_bytes": 3848290697216, "used_bytes": 2916826112000, "utilization_percent": 53.1 },
21      "counts": {
22        "clusters": 8,
23        "connected_clusters": 6,
24        "nodes": 247,
25        "namespaces": 89,
26        "workloads": 1842,
27        "pods": 5263,
28        "containers": 11824,
29        "persistent_volumes": 412,
30        "recommendations": 38
31      }
32    },
33    "cost": {
34      "current_run_rate_hourly": { "amount": "412.5800", "currency": "USD" },
35      "last_updated_at": "2026-05-21T10:29:14Z",
36      "excluded_cluster_ids": ["7d2c9e41-0b8a-4f63-a1d5-3e9f0c7b2a64"]
37    }
38  },
39  "meta": {
40    "request_id": "0196f1c2-14c3-7b02-bf41-e7aedafad03a",
41    "applied_at": "2026-05-21T10:30:00Z"
42  }
43}

Stale clusters (is_stale=true) are excluded from connected_clusters but counted in clusters.

Example error response

json

1{
2  "data": null,
3  "meta": {
4    "request_id": "0196f1c2-199d-7dd3-9350-e0dc1a6d173c",
5    "applied_at": "2026-05-21T10:30:05Z"
6  },
7  "error": {
8    "code": "UNAUTHORIZED",
9    "message": "missing authorization header",
10    "details": [{ "reason": "missing_header" }]
11  }
12}

See Error Handling for the full code catalog and retry guidance.

Common errors

HTTP	`error.code`	When
401	`UNAUTHORIZED`	Missing or invalid Bearer token.
403	`FORBIDDEN`	Token lacks the `organization:read` scope.
422	`INVALID_COST_MODE`	`?cost_mode=` was supplied, not accepted on the snapshot endpoint.
429	`RATE_LIMITED`	Per-key quota exceeded. See `Retry-After`.
500	`INTERNAL_ERROR`	Server-side failure.

Get organization dashboard

GET /v1/organization/dashboard

Required scope: organization:read

Returns the month-to-date billed cost, savings potential from open recommendations (current hourly potential + count), and the top clusters ranked by month-to-date cost. The response does not include a projected-monthly value; multiply current_run_rate_hourly by the number of hours in a month for that estimate.

The dashboard accepts ?cost_mode=. month_to_date.billed_cost genuinely differs between fully_loaded and workload_only. snapshot.cost.current_run_rate_hourly and savings do not vary by mode: the run rate is always fully loaded (see Get organization snapshot) and savings come from your recommendations. The month-to-date figures, including each top cluster's month_to_date_cost and the ranking, follow the mode. See Cost Modes.

The snapshot block is an embedded copy of the /v1/organization body.

Query parameters

Name	Type	Default	Allowed values	Description
`cost_mode`	string	`fully_loaded`	`fully_loaded`, `workload_only`	Cost attribution mode. Changes `month_to_date.billed_cost`; does not change `snapshot.cost` or `savings`.
`top_clusters_limit`	integer	`5`	`1..20`	How many clusters to embed under `top_clusters`, sorted by month-to-date cost descending.

Example request

bash

curl -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://public-api.kubeadapt.io/v1/organization/dashboard?cost_mode=fully_loaded&top_clusters_limit=5"

Example response

json

1{
2  "data": {
3    "organization_id": "f47a9b21-3c5d-4e6f-8a9b-0c1d2e3f4a5b",
4    "snapshot": {
5      "id": "f47a9b21-3c5d-4e6f-8a9b-0c1d2e3f4a5b",
6      "kind": "Organization",
7      "metadata": {
8        "name": "Northwind Holdings",
9        "domain": "northwind.example",
10        "plan_type": "growth",
11        "is_active": true,
12        "created_at": "2025-11-04T09:12:00Z"
13      },
14      "capacity": {
15        "cpu": { "total_cores": 1248.0, "allocatable_cores": 1162.4 },
16        "memory": { "total_bytes": 5497558138880, "allocatable_bytes": 5119018639360 },
17        "gpu": { "total": 24, "allocatable": 24, "model": "NVIDIA A10G" },
18        "storage": { "total_bytes": 107374182400000 }
19      },
20      "utilization": {
21        "cpu": { "requested_cores": 842.7, "used_cores": 612.3, "utilization_percent": 49.1 },
22        "memory": { "requested_bytes": 3848290697216, "used_bytes": 2916826112000, "utilization_percent": 53.1 },
23        "counts": {
24          "clusters": 8,
25          "connected_clusters": 6,
26          "nodes": 247,
27          "namespaces": 89,
28          "workloads": 1842,
29          "pods": 5263,
30          "containers": 11824,
31          "persistent_volumes": 412,
32          "recommendations": 38
33        }
34      },
35      "cost": {
36        "current_run_rate_hourly": { "amount": "412.5800", "currency": "USD" },
37        "last_updated_at": "2026-05-21T10:29:14Z",
38        "excluded_cluster_ids": ["7d2c9e41-0b8a-4f63-a1d5-3e9f0c7b2a64"]
39      }
40    },
41    "month_to_date": {
42      "billed_cost": { "amount": "24832.1700", "currency": "USD" },
43      "calendar": {
44        "month": "2026-05",
45        "days_elapsed": 21,
46        "days_in_month": 31,
47        "month_start_at": "2026-05-01T00:00:00Z"
48      }
49    },
50    "savings": {
51      "current_hourly_potential": { "amount": "5.7800", "currency": "USD" },
52      "recommendation_count": 38
53    },
54    "top_clusters": [
55      {
56        "cluster": { "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "prod-eu-west-1" },
57        "current_run_rate_hourly": { "amount": "82.4100", "currency": "USD" },
58        "month_to_date_cost": { "amount": "9714.2800", "currency": "USD" }
59      },
60      {
61        "cluster": { "id": "a8d3e1b2-f4c6-4789-9bde-2345678901cd", "name": "prod-us-east-1" },
62        "current_run_rate_hourly": { "amount": "61.0700", "currency": "USD" },
63        "month_to_date_cost": { "amount": "7202.6400", "currency": "USD" }
64      },
65      {
66        "cluster": { "id": "9e8d7c6b-5a4f-3e2d-1b0a-fedcba987654", "name": "prod-ap-southeast-2" },
67        "current_run_rate_hourly": { "amount": "44.8900", "currency": "USD" },
68        "month_to_date_cost": { "amount": "5294.0200", "currency": "USD" }
69      },
70      {
71        "cluster": { "id": "7f6e5d4c-3b2a-1098-7654-321fedcba098", "name": "staging-us-central1" },
72        "current_run_rate_hourly": { "amount": "32.1400", "currency": "USD" },
73        "month_to_date_cost": { "amount": "3789.2900", "currency": "USD" }
74      },
75      {
76        "cluster": { "id": "1a2b3c4d-5e6f-7890-1234-56789abcdef0", "name": "dev-eu-central-1" },
77        "current_run_rate_hourly": { "amount": "25.0300", "currency": "USD" },
78        "month_to_date_cost": { "amount": "2951.6800", "currency": "USD" }
79      }
80    ]
81  },
82  "meta": {
83    "request_id": "0196f1c2-d557-7501-81d7-0287fb76f796",
84    "applied_at": "2026-05-21T10:30:00Z",
85    "cost_mode": "fully_loaded"
86  }
87}

The meta.cost_mode echo confirms which mode the response was computed in. Switch to ?cost_mode=workload_only and month_to_date's money fields will shift, because idle capacity and overhead are attributed differently in each mode. savings does not shift; it comes from your recommendations, which have no per-mode split.

Common errors

HTTP	`error.code`	When
401	`UNAUTHORIZED`	Missing or invalid Bearer token.
403	`FORBIDDEN`	Token lacks the `organization:read` scope.
422	`INVALID_COST_MODE`	`?cost_mode=` is not one of `fully_loaded` or `workload_only`.
422	`VALIDATION_ERROR`	`top_clusters_limit` outside 1..20, or non-integer.
429	`RATE_LIMITED`	Per-key quota exceeded.
500	`INTERNAL_ERROR`	Server-side failure.

Get organization snapshot

Example request

Example response

Example error response

Common errors

Get organization dashboard

Query parameters

Example request

Example response

Common errors

See also

Related