# List Deployments

### Endpoint

**POST** `/api/k8s/v2/deployments/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

The request body requires a time range and supports filtering by fields:

```json
{
  "start": "2025-08-24T07:21:36.944Z",
  "end": "2025-08-24T08:51:36.944Z", 
  "namespaces": ["groundcover"],
  "sources": []
}
```

**Parameters**

| Parameter    | Type   | Required | Description                                                                |
| ------------ | ------ | -------- | -------------------------------------------------------------------------- |
| `start`      | string | Yes      | Start time in ISO 8601 UTC format (e.g., `"2025-08-24T07:21:36.944Z"`)     |
| `end`        | string | Yes      | End time in ISO 8601 UTC format (e.g., `"2025-08-24T08:51:36.944Z"`)       |
| `namespaces` | array  | No       | Array of namespace names to filter by (e.g., `["groundcover", "default"]`) |
| `sources`    | array  | No       | Source filters                                                             |

### Response

#### Response Schema

```json
{
  "deployments": [
    {
      "name": "string",
      "namespace": "string", 
      "workloadName": "string",
      "creationTime": "2023-08-30T18:27:01Z",
      "cluster": "string",
      "env": "string",
      "available": 1,
      "desired": 1,
      "ready": 1,
      "conditions": [
        {
          "type": "string",
          "status": "string",
          "lastProbeTime": null,
          "lastHeartbeatTime": null,
          "lastTransitionTime": "string",
          "reason": "string",
          "message": "string"
        }
      ],
      "warnings": [],
      "id": "string",
      "resourceVersion": 0
    }
  ]
}
```

**Field Descriptions**

| Field                             | Type        | Description                                           |
| --------------------------------- | ----------- | ----------------------------------------------------- |
| `deployments`                     | array       | Array of deployment objects                           |
| `name`                            | string      | Deployment name                                       |
| `namespace`                       | string      | Kubernetes namespace                                  |
| `workloadName`                    | string      | Associated workload name                              |
| `creationTime`                    | string      | Deployment creation timestamp in ISO 8601 format      |
| `cluster`                         | string      | Kubernetes cluster name                               |
| `env`                             | string      | Environment name (e.g., `"prod"`, `"staging"`)        |
| `available`                       | integer     | Number of available replicas                          |
| `desired`                         | integer     | Number of desired replicas                            |
| `ready`                           | integer     | Number of ready replicas                              |
| `conditions`                      | array       | Array of deployment condition objects                 |
| `conditions[].type`               | string      | Condition type (e.g., `"Available"`, `"Progressing"`) |
| `conditions[].status`             | string      | Condition status (`"True"`, `"False"`, `"Unknown"`)   |
| `conditions[].lastProbeTime`      | string/null | Last time the condition was probed                    |
| `conditions[].lastHeartbeatTime`  | string/null | Last time the condition was updated                   |
| `conditions[].lastTransitionTime` | string      | Last time the condition transitioned                  |
| `conditions[].reason`             | string      | Machine-readable reason for the condition             |
| `conditions[].message`            | string      | Human-readable message explaining the condition       |
| `warnings`                        | array       | Array of warning messages (usually empty)             |
| `id`                              | string      | Unique identifier for the deployment                  |
| `resourceVersion`                 | integer     | Kubernetes resource version                           |

**Common Condition Types**

| Type          | Description                                         |
| ------------- | --------------------------------------------------- |
| `Available`   | Deployment has minimum availability                 |
| `Progressing` | Deployment is making progress towards desired state |

**Common Condition Reasons**

| Reason                     | Description                                         |
| -------------------------- | --------------------------------------------------- |
| `MinimumReplicasAvailable` | Deployment has minimum number of replicas available |
| `NewReplicaSetAvailable`   | New ReplicaSet has successfully progressed          |

### Examples

#### Basic Request

Get deployments for a specific time range:

```bash
curl 'https://api.groundcover.com/api/k8s/v2/deployments/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 '{"start":"2025-08-24T07:21:36.944Z","end":"2025-08-24T08:51:36.944Z","namespaces":[],"sources":[]}'
```

#### Filter by Namespace

Get deployments from specific namespaces:

```bash
curl 'https://api.groundcover.com/api/k8s/v2/deployments/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 '{"start":"2025-08-24T07:21:36.944Z","end":"2025-08-24T08:51:36.944Z","namespaces":["groundcover","monitoring"],"sources":[]}'
```

#### Response Example

```json
{
  "deployments": [
    {
      "name": "db-manager",
      "namespace": "groundcover",
      "workloadName": "db-manager",
      "creationTime": "2023-08-30T18:27:01Z",
      "cluster": "karma-cluster",
      "env": "prod",
      "available": 1,
      "desired": 1,
      "ready": 1,
      "conditions": [
        {
          "type": "Available",
          "status": "True",
          "lastProbeTime": null,
          "lastHeartbeatTime": null,
          "lastTransitionTime": "2025-08-22T06:18:27Z",
          "reason": "MinimumReplicasAvailable",
          "message": "Deployment has minimum availability."
        },
        {
          "type": "Progressing",
          "status": "True",
          "lastProbeTime": null,
          "lastHeartbeatTime": null,
          "lastTransitionTime": "2023-08-30T18:27:01Z",
          "reason": "NewReplicaSetAvailable",
          "message": "ReplicaSet \"db-manager-867bc8f5b8\" has successfully progressed."
        }
      ],
      "warnings": [],
      "id": "f3b1f4a5-f38a-4c63-a7c0-9333fcbf1906",
      "resourceVersion": 747039184
    }
  ]
}
```

### Time Range Guidelines

* Use ISO 8601 UTC format for timestamps
* Typical time ranges: 1-24 hours for operational monitoring
* Maximum recommended range: 7 days
* Format: `YYYY-MM-DDTHH:MM:SS.sssZ`


---

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