Metrics API

Query container, pod, and node metrics.

The Metrics API provides access to current and historical metrics for all resources monitored by your agents.

Base URL: https://YOUR_KUBEWATCH_URL (your KubeWatch instance, shown in your dashboard)

All requests require authentication via Authorization: Bearer <token> or X-API-Key: <key>.

List containers

GET /api/v1/containers

Returns all containers with their most recent metrics snapshot.

Query parameters:

Parameter	Type	Description
`agentId`	string	Filter by agent ID
`status`	string	Filter by status: `running`, `stopped`, `exited`
`image`	string	Filter by image name substring
`limit`	integer	Max results (default: 100, max: 1000)
`offset`	integer	Pagination offset

Response 200:

{
  "containers": [
    {
      "id": "container_abc123",
      "name": "web-app",
      "image": "nginx:1.25",
      "status": "running",
      "agentId": "agent_abc123xyz",
      "agentName": "prod-k8s",
      "cpuPercent": 12.4,
      "memoryMB": 256,
      "memoryLimitMB": 512,
      "networkRxBytes": 1048576,
      "networkTxBytes": 524288,
      "restartCount": 0,
      "uptimeSeconds": 86400,
      "updatedAt": "2026-06-12T10:00:05Z"
    }
  ],
  "total": 42
}

List pods

GET /api/v1/pods

Returns all pods reported by Kubernetes agents.

Query parameters: agentId, namespace, status, limit, offset

Response 200:

{
  "pods": [
    {
      "name": "web-app-7d9f8-xk2pq",
      "namespace": "default",
      "status": "Running",
      "nodeName": "worker-01",
      "agentId": "agent_abc123xyz",
      "restartCount": 0,
      "age": "5d",
      "updatedAt": "2026-06-12T10:00:05Z"
    }
  ],
  "total": 8
}

List nodes

GET /api/v1/nodes

Returns all nodes reported by Kubernetes agents.

Query parameters: agentId, status, limit, offset

Response 200:

{
  "nodes": [
    {
      "name": "worker-01",
      "status": "Ready",
      "agentId": "agent_abc123xyz",
      "cpuCapacity": 4,
      "cpuAllocatable": 3.8,
      "cpuUsedPercent": 42.1,
      "memoryCapacityMB": 8192,
      "memoryAllocatableMB": 7680,
      "memoryUsedMB": 5120,
      "podCount": 12,
      "podCapacity": 110,
      "updatedAt": "2026-06-12T10:00:05Z"
    }
  ],
  "total": 3
}

Cluster summary

GET /api/v1/cluster/summary

Returns an aggregate summary across all agents (or a specific agent).

Query parameters: agentId (optional)

Response 200:

{
  "totalContainers": 42,
  "runningContainers": 40,
  "stoppedContainers": 2,
  "totalPods": 8,
  "totalNodes": 3,
  "avgCpuPercent": 28.4,
  "totalMemoryUsedMB": 12288,
  "totalMemoryCapacityMB": 32768,
  "firingAlerts": 1,
  "connectedAgents": 2,
  "updatedAt": "2026-06-12T10:00:05Z"
}

Historical metrics

GET /api/v1/containers/{containerId}/metrics

Returns time-series metrics for a specific container.

Query parameters:

Parameter	Type	Default	Description
`startTime`	ISO 8601	1 hour ago	Start of the time range
`endTime`	ISO 8601	now	End of the time range
`resolution`	string	`auto`	Data resolution: `1m`, `5m`, `1h`, `1d`

Response 200:

{
  "containerId": "container_abc123",
  "metrics": [
    {
      "timestamp": "2026-06-12T09:00:00Z",
      "cpuPercent": 11.2,
      "memoryMB": 248,
      "networkRxBytes": 102400,
      "networkTxBytes": 51200
    },
    {
      "timestamp": "2026-06-12T09:05:00Z",
      "cpuPercent": 14.8,
      "memoryMB": 261,
      "networkRxBytes": 108000,
      "networkTxBytes": 53000
    }
  ],
  "resolution": "5m"
}