# List Clusters

### 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

```bash
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

```json
{
  "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
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/remote-access-and-apis/api-examples/list-clusters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.