KubeadaptDocsBack to site
Sign inStart free
DocsAPI ReferenceCLI
    • Discovery
    • Organization
    • Clusters
    • Namespaces
    • Workloads
    • Nodes
    • Node Groups
    • Recommendations
    • Teams
    • Departments
    • Cost Explorer
    • Cost Trends
Docs homev1Api ReferenceOrganization

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.

Two endpoints cover the tenant-level surface. GET /v1/organization returns the static snapshot: identity, aggregate capacity, utilization counts, and current hourly run rate across every cluster 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 run rate — 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.

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    }
37  },
38  "meta": {
39    "request_id": "req_01J5K3V0Q7Y4XR8A2B3C5D7E9F",
40    "applied_at": "2026-05-21T10:30:00Z"
41  }
42}

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": "req_01J5K3V0Q7Y4XR8A2B3C5D7E9G",
5    "applied_at": "2026-05-21T10:30:05Z"
6  },
7  "error": {
8    "code": "UNAUTHORIZED",
9    "message": "missing or invalid bearer token"
10  }
11}

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

Common errors

HTTPerror.codeWhen
401UNAUTHORIZEDMissing or invalid Bearer token.
403FORBIDDENToken lacks the organization:read scope.
422INVALID_COST_MODE?cost_mode= was supplied, not accepted on the snapshot endpoint.
429RATE_LIMITEDPer-key quota exceeded. See Retry-After.
500INTERNAL_ERRORServer-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 hourly run rate. 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=. fully_loaded and workload_only return materially different numbers. See Cost Modes.

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

Query parameters

NameTypeDefaultAllowed valuesDescription
cost_modestringfully_loadedfully_loaded, workload_onlyCost attribution mode. Genuinely changes the returned numbers.
top_clusters_limitinteger51..20How many clusters to embed under top_clusters, sorted by hourly run rate 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      }
39    },
40    "month_to_date": {
41      "billed_cost": { "amount": "24832.1700", "currency": "USD" },
42      "calendar": {
43        "month": "2026-05",
44        "days_elapsed": 21,
45        "days_in_month": 31,
46        "month_start_at": "2026-05-01T00:00:00Z"
47      }
48    },
49    "savings": {
50      "current_hourly_potential": { "amount": "5.7800", "currency": "USD" },
51      "recommendation_count": 38
52    },
53    "top_clusters": [
54      {
55        "cluster": { "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "prod-eu-west-1" },
56        "current_run_rate_hourly": { "amount": "82.4100", "currency": "USD" },
57        "month_to_date_cost": { "amount": "9714.2800", "currency": "USD" }
58      },
59      {
60        "cluster": { "id": "a8d3e1b2-f4c6-4789-9bde-2345678901cd", "name": "prod-us-east-1" },
61        "current_run_rate_hourly": { "amount": "61.0700", "currency": "USD" },
62        "month_to_date_cost": { "amount": "7202.6400", "currency": "USD" }
63      },
64      {
65        "cluster": { "id": "9e8d7c6b-5a4f-3e2d-1b0a-fedcba987654", "name": "prod-ap-southeast-2" },
66        "current_run_rate_hourly": { "amount": "44.8900", "currency": "USD" },
67        "month_to_date_cost": { "amount": "5294.0200", "currency": "USD" }
68      },
69      {
70        "cluster": { "id": "7f6e5d4c-3b2a-1098-7654-321fedcba098", "name": "staging-us-central1" },
71        "current_run_rate_hourly": { "amount": "32.1400", "currency": "USD" },
72        "month_to_date_cost": { "amount": "3789.2900", "currency": "USD" }
73      },
74      {
75        "cluster": { "id": "1a2b3c4d-5e6f-7890-1234-56789abcdef0", "name": "dev-eu-central-1" },
76        "current_run_rate_hourly": { "amount": "25.0300", "currency": "USD" },
77        "month_to_date_cost": { "amount": "2951.6800", "currency": "USD" }
78      }
79    ]
80  },
81  "meta": {
82    "request_id": "req_01J5K3V8N2P4QR8A2B3C5D7E9H",
83    "applied_at": "2026-05-21T10:30:00Z",
84    "cost_mode": "fully_loaded"
85  }
86}

The meta.cost_mode echo confirms which mode the response was computed in. Switch to ?cost_mode=workload_only and every money field in month_to_date and savings will shift, because the attribution logic differs per mode.

Common errors

HTTPerror.codeWhen
401UNAUTHORIZEDMissing or invalid Bearer token.
403FORBIDDENToken lacks the organization:read scope.
422INVALID_COST_MODE?cost_mode= is not one of fully_loaded or workload_only.
422VALIDATION_ERRORtop_clusters_limit outside 1..20, or non-integer.
429RATE_LIMITEDPer-key quota exceeded.
500INTERNAL_ERRORServer-side failure.

See also

  • Clusters, drill from a top-clusters entry into the full cluster body or the per-cluster sub-resources.
  • Cost Modes, the fully_loaded vs workload_only model and where it does and doesn't apply.
  • Cost Trends, tenant-wide cost time series via /v1/organizations/dashboard/cost-trend.
  • Cost Explorer, aggregated cost queries with grouping, filtering, and KPI summary.
  • Error Handling, the full error code catalog and retry semantics.

Related

  • Clusters
  • Cost Modes
  • Cost Trends
  • Cost Explorer
  • Error Handling
PreviousDiscoveryAPI ReferenceNextClustersAPI Reference

On this page

  • 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
Edit this page
Kubeadapt

Kubernetes FinOps platform. Cost visibility, rightsizing, and capacity planning that pays for itself in 30 days.

Product

  • Cost Monitoring
  • Cost Attribution
  • Workload Rightsizing
  • Recommendations
  • Smart Alerting
  • Best Practices
  • Network Cross-AZ

Resources

  • Documentation
  • Status Page
  • Feature Requests

Company

  • About Us
  • Security
  • Careers
  • Contact

© 2026 Kubeadapt. All rights reserved.

PrivacyTermsSecurity