List Deployments

Get a list of Kubernetes deployments with status information, replica counts, and operational conditions for a specified time range.

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:

{
  "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

{
  "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:

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:

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

{
  "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