# List Workloads

### Endpoint

```
POST /api/k8s/v3/workloads/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 | Default  | Description                                                     |
| ------------ | ------- | -------- | -------- | --------------------------------------------------------------- |
| `conditions` | Array   | No       | `[]`     | Filter conditions for workloads                                 |
| `limit`      | Integer | No       | `100`    | Maximum number of workloads to return (1-1000)                  |
| `skip`       | Integer | No       | `0`      | Number of workloads to skip for pagination                      |
| `order`      | String  | No       | `"desc"` | Sort order: `"asc"` or `"desc"`                                 |
| `sortBy`     | String  | No       | `"rps"`  | Field to sort by (e.g., `"rps"`, `"cpuUsage"`, `"memoryUsage"`) |
| `sources`    | Array   | No       | `[]`     | Filter by data sources                                          |

### Response

The response contains a paginated list of workloads with their metrics and metadata.

#### Response Fields

| Field       | Type    | Description                         |
| ----------- | ------- | ----------------------------------- |
| `total`     | Integer | Total number of workloads available |
| `workloads` | Array   | Array of workload objects           |

#### Workload Object Fields

| Field             | Type    | Description                                                                     |
| ----------------- | ------- | ------------------------------------------------------------------------------- |
| `uid`             | String  | Unique identifier for the workload                                              |
| `envType`         | String  | Environment type (e.g., `"k8s"`)                                                |
| `env`             | String  | Environment name (e.g., `"prod"`, `"ga"`, `"alpha"`)                            |
| `cluster`         | String  | Kubernetes cluster name                                                         |
| `namespace`       | String  | Kubernetes namespace                                                            |
| `workload`        | String  | Workload name                                                                   |
| `kind`            | String  | Kubernetes resource kind (e.g., `"ReplicaSet"`, `"StatefulSet"`, `"DaemonSet"`) |
| `resourceVersion` | Integer | Kubernetes resource version                                                     |
| `ready`           | Boolean | Whether the workload is ready                                                   |
| `podsCount`       | Integer | Number of pods in the workload                                                  |
| `p50`             | Float   | 50th percentile response time in seconds                                        |
| `p95`             | Float   | 95th percentile response time in seconds                                        |
| `p99`             | Float   | 99th percentile response time in seconds                                        |
| `rps`             | Float   | Requests per second                                                             |
| `errorRate`       | Float   | Error rate as a decimal (e.g., 0.004 = 0.4%)                                    |
| `cpuLimit`        | Integer | CPU limit in millicores (0 = no limit)                                          |
| `cpuUsage`        | Float   | Current CPU usage in millicores                                                 |
| `memoryLimit`     | Integer | Memory limit in bytes (0 = no limit)                                            |
| `memoryUsage`     | Integer | Current memory usage in bytes                                                   |
| `issueCount`      | Integer | Number of issues detected                                                       |

### Examples

#### Basic Request

```bash
curl 'https://api.groundcover.com/api/k8s/v3/workloads/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 '{"conditions":[],"limit":100,"order":"desc","skip":0,"sortBy":"rps","sources":[]}'
```

#### Response Example

```json
{
  "total": 6314,
  "workloads": [
    {
      "uid": "824b00bf-db68-47b5-8a53-9abd98bf7c0a",
      "envType": "k8s",
      "env": "ga",
      "cluster": "akamai-lk41ok",
      "namespace": "groundcover-incloud",
      "workload": "groundcover-incloud-vector",
      "kind": "ReplicaSet",
      "resourceVersion": 651723275,
      "ready": true,
      "podsCount": 5,
      "p50": 0.0005824280087836087,
      "p95": 0.005730729550123215,
      "p99": 0.0327172689139843,
      "rps": 5526.0027359781125,
      "errorRate": 0,
      "cpuLimit": 0,
      "cpuUsage": 50510.15252730218,
      "memoryLimit": 214748364800,
      "memoryUsage": 46527352832,
      "issueCount": 0
    }
  ]
}
```

### Pagination

To retrieve all workloads, use pagination by incrementing the `skip` parameter:

#### Fetching All Results

```bash
# First batch (0-99)
curl 'https://api.groundcover.com/api/k8s/v3/workloads/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 '{"conditions":[],"limit":100,"order":"desc","skip":0,"sortBy":"rps","sources":[]}'

# Second batch (100-199)
curl 'https://api.groundcover.com/api/k8s/v3/workloads/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 '{"conditions":[],"limit":100,"order":"desc","skip":100,"sortBy":"rps","sources":[]}'

# Continue incrementing skip by 100 until you reach the total count
```

#### Pagination Logic

To fetch all results programmatically:

1. Start with `skip=0` and `limit=100` (or your preferred page size)
2. Check the `total` field in the response
3. Continue making requests, incrementing `skip` by your `limit` value
4. Stop when `skip` >= `total`

**Example calculation:**

* If `total` is 6314 and `limit` is 100
* You need ⌈6314/100⌉ = 64 requests
* Last request: `skip=6300`, `limit=100` (returns 14 items)