List Clusters

Retrieve a list of Kubernetes clusters with their resource usage metrics, metadata, and health information.

Endpoint

POST /api/k8s/v3/clusters/list

Authentication

This endpoint requires API Key authentication via the Authorization header.

Headers

Header	Required	Description
Authorization	Yes	Bearer token with your API key
X-Backend-Id	Yes	Your backend identifier
Content-Type	Yes	Must be application/json
Accept	Yes	Must be application/json

Request Body

Parameter	Type	Required	Description
sources	Array	No	Filter by data sources (empty array for all sources)

Response

The response contains an array of clusters with detailed resource usage and metadata.

Response Fields

Field	Type	Description
clusters	Array	Array of cluster objects
totalCount	Integer	Total number of clusters

Cluster Object Fields

Field	Type	Description
name	String	Cluster name
env	String	Environment (e.g., "prod", "ga", "beta", "alpha", "latest")
creationTimestamp	String	When the cluster was created (ISO 8601)
cloudProvider	String	Cloud provider (e.g., "AWS", "GCP", "Azure")
kubernetesVersion	String	Kubernetes version
nodesCount	Integer	Number of nodes in the cluster
issueCount	Integer	Number of issues detected

CPU Metrics

Field	Type	Description
cpuUsage	Integer	Current CPU usage in millicores
cpuLimit	Integer	CPU limits set on resources in millicores
cpuAllocatable	Integer	Total allocatable CPU in millicores
cpuRequest	Integer	Total CPU requests in millicores
cpuUsageAllocatablePercent	Float	CPU usage as percentage of allocatable
cpuRequestAllocatablePercent	Float	CPU requests as percentage of allocatable
cpuUsageRequestPercent	Float	CPU usage as percentage of requests
cpuUsageLimitPercent	Float	CPU usage as percentage of limits
cpuLimitAllocatablePercent	Float	CPU limits as percentage of allocatable

Memory Metrics

Field	Type	Description
memoryUsage	Integer	Current memory usage in bytes
memoryLimit	Integer	Memory limits set on resources in bytes
memoryAllocatable	Integer	Total allocatable memory in bytes
memoryRequest	Integer	Total memory requests in bytes
memoryUsageAllocatablePercent	Float	Memory usage as percentage of allocatable
memoryRequestAllocatablePercent	Float	Memory requests as percentage of allocatable
memoryUsageRequestPercent	Float	Memory usage as percentage of requests
memoryUsageLimitPercent	Float	Memory usage as percentage of limits
memoryLimitAllocatablePercent	Float	Memory limits as percentage of allocatable

Pod Information

Field	Type	Description
pods	Object	Pod counts by status (e.g., {"Running": 157, "Succeeded": 4})

Examples

Basic Request

curl 'https://api.groundcover.com/api/k8s/v3/clusters/list' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'content-type: application/json' \
  -H 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --data-raw '{"sources":[]}'

Response Example

{
  "clusters": [
    {
      "name": "production-cluster",
      "env": "prod",
      "cpuUsage": 126640,
      "cpuLimit": 289800,
      "cpuAllocatable": 302820,
      "cpuRequest": 187975,
      "cpuUsageAllocatablePercent": 41.82,
      "cpuRequestAllocatablePercent": 62.07,
      "cpuUsageRequestPercent": 67.37,
      "cpuUsageLimitPercent": 43.70,
      "cpuLimitAllocatablePercent": 95.70,
      "memoryUsage": 242994409472,
      "memoryLimit": 604262891520,
      "memoryAllocatable": 1227361431552,
      "memoryRequest": 495549677568,
      "memoryUsageAllocatablePercent": 19.80,
      "memoryRequestAllocatablePercent": 40.38,
      "memoryUsageRequestPercent": 49.04,
      "memoryUsageLimitPercent": 40.21,
      "memoryLimitAllocatablePercent": 49.23,
      "nodesCount": 6,
      "pods": {
        "Running": 109,
        "Succeeded": 3
      },
      "issueCount": 1,
      "creationTimestamp": "2021-11-01T14:37:31Z",
      "cloudProvider": "AWS",
      "kubernetesVersion": "v1.30.14-eks-931bdca"
    }
  ],
  "totalCount": 116
}