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


---

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