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