List Nodes with Resource Information

Endpoint

POST /api/k8s/v2/nodes/info-with-resources

Authentication

This endpoint requires API key authentication.

Headers

Header	Value	Description
Authorization	Bearer <YOUR_API_KEY>	Your groundcover API key
Content-Type	application/json	Request body format
X-Backend-Id	<YOUR_BACKEND_ID>	Your backend identifier

Request Body

Field	Type	Required	Description
start	string	Yes	Start time in ISO 8601 UTC format
end	string	Yes	End time in ISO 8601 UTC format
sources	array	No	Source filters (e.g., cluster filters)
limit	integer	No	Maximum number of nodes to return (default: 100)

Sources Structure (Cluster Filter)

{
  "key": "cluster",
  "type": "string",
  "origin": "root", 
  "filters": [
    {
      "op": "eq",
      "value": "cluster-name"
    }
  ]
}

Example Request

curl -L \
  --request POST \
  --url 'https://api.groundcover.com/api/k8s/v2/nodes/info-with-resources' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --data '{
    "start": "2025-01-27T12:00:00.000Z",
    "end": "2025-01-27T14:00:00.000Z",
    "sources": [
      {
        "key": "cluster",
        "type": "string",
        "origin": "root",
        "filters": [
          {
            "op": "eq",
            "value": "my-cluster"
          }
        ]
      }
    ],
    "limit": 100,
    "nameFilter": ""
  }'

Response

{
  "nodes": [
    {
      "uid": "node-uid",
      "name": "node-name",
      "cluster": "cluster-name",
      "env": "environment-name",
      "creationTimestamp": "2025-01-01T10:00:00Z",
      "labels": {
        "kubernetes.io/arch": "amd64",
        "kubernetes.io/os": "linux",
        "node.kubernetes.io/instance-type": "t3.medium"
      },
      "addresses": [
        {
          "type": "InternalIP",
          "address": "10.0.1.100"
        },
        {
          "type": "ExternalIP", 
          "address": "203.0.113.100"
        }
      ],
      "nodeInfo": {
        "kubeletVersion": "v1.24.0",
        "kubeProxyVersion": "v1.24.0",
        "operatingSystem": "linux",
        "architecture": "amd64",
        "containerRuntimeVersion": "containerd://1.6.0",
        "kernelVersion": "5.4.0-91-generic",
        "osImage": "Ubuntu 20.04.3 LTS"
      },
      "capacity": {
        "cpu": "2",
        "memory": "8Gi",
        "pods": "110"
      },
      "allocatable": {
        "cpu": "1940m",
        "memory": "7Gi", 
        "pods": "110"
      },
      "usage": {
        "cpu": "500m",
        "memory": "3Gi"
      },
      "ready": true,
      "conditions": [
        {
          "type": "Ready",
          "status": "True",
          "lastTransitionTime": "2025-01-01T10:05:00Z",
          "reason": "KubeletReady",
          "message": "kubelet is posting ready status"
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
nodes	array	Array of node objects
nodes[].uid	string	Unique identifier for the node
nodes[].name	string	Node name
nodes[].cluster	string	Cluster name
nodes[].env	string	Environment name
nodes[].creationTimestamp	string	Node creation time in ISO 8601 format
nodes[].labels	object	Node labels key-value pairs
nodes[].addresses	array	Node IP addresses (internal/external)
nodes[].nodeInfo	object	Node system information
nodes[].capacity	object	Total node resource capacity
nodes[].allocatable	object	Allocatable resources (capacity minus system reserved)
nodes[].usage	object	Current resource usage
nodes[].ready	boolean	Node readiness status
nodes[].conditions	array	Node condition details

Filter Operations

Operator	Description
eq	Equals
ne	Not equals
gt	Greater than
lt	Less than
contains	Contains substring

Common Use Cases

Get All Nodes

{
  "start": "2025-01-27T12:00:00.000Z",
  "end": "2025-01-27T14:00:00.000Z",
  "limit": 100
}

Filter by Specific Cluster

{
  "start": "2025-01-27T12:00:00.000Z",
  "end": "2025-01-27T14:00:00.000Z",
  "sources": [
    {
      "key": "cluster",
      "type": "string", 
      "origin": "root",
      "filters": [{"op": "eq", "value": "production-cluster"}]
    }
  ],
  "limit": 100
}