Metrics API

Query container, pod, and node data pushed by your agents.

The Metrics API gives you read access to the current state of everything your agents report.

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

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

These endpoints return the full current list for your organization as a bare JSON array. There's no `agentId`/`status`/`namespace` filtering or `limit`/`offset` pagination on the server side today, so filter and paginate client-side if you need a subset.

List containers

GET /api/v1/containers

Returns every Docker container across your agents, with its latest metrics snapshot already merged in.

Response 200

[
  {
    "id": "a1b2c3d4e5f6...",
    "shortId": "a1b2c3d4e5f6",
    "name": "web-app",
    "image": "nginx:1.25",
    "status": "running",
    "state": "running",
    "created": "2026-06-01T10:00:00Z",
    "source": "docker",
    "agentId": "agent_abc123xyz",
    "cpuPercent": 12.4,
    "memoryUsageMB": 256,
    "memoryLimitMB": 512,
    "memoryPercent": 50,
    "netRxBytes": 1048576,
    "netTxBytes": 524288,
    "blkReadBytes": 0,
    "blkWriteBytes": 0,
    "ports": []
  }
]

List pods

GET /api/v1/pods

Returns every Kubernetes pod across your agents. cpuCores, cpuPercent, memoryBytes, and memoryPercent are only populated if metrics-server is installed on that cluster.

Response 200

[
  {
    "name": "web-app-7d9f8-xk2pq",
    "namespace": "default",
    "phase": "Running",
    "nodeName": "worker-01",
    "podIP": "10.244.1.12",
    "labels": {},
    "containers": [],
    "startTime": "2026-06-07T10:00:00Z",
    "restarts": 0,
    "ready": true,
    "cpuCores": 0.12,
    "cpuPercent": 24,
    "memoryBytes": 134217728,
    "memoryPercent": 33
  }
]

List nodes

GET /api/v1/nodes

Returns every Kubernetes node across your agents, including the capacity/allocatable/usage breakdown behind the dashboard's Nodes page.

Response 200

[
  {
    "name": "worker-01",
    "status": "Ready",
    "roles": ["worker"],
    "kubeletVersion": "v1.31.2",
    "osImage": "Ubuntu 22.04.4 LTS",
    "architecture": "amd64",
    "capacity": { "cpu": "4", "memory": "8144936Ki", "pods": "110", "ephemeralStorage": "20620432Ki" },
    "allocatable": { "cpu": "3800m", "memory": "7615336Ki", "pods": "110", "ephemeralStorage": "18989540Ki" },
    "usage": {
      "cpuCores": 4, "cpuSystemReservedCores": 0.2, "cpuWorkloadReservedCores": 1.6,
      "memoryGiB": 7.77, "memorySystemReservedGiB": 0.5, "memoryWorkloadReservedGiB": 2.1,
      "ephemeralStorageGiB": 19.66, "ephemeralStorageSystemReservedGiB": 1.5, "ephemeralStorageWorkloadReservedGiB": 0,
      "pods": 110, "podsUsed": 24
    },
    "labels": {}
  }
]

Cluster summary

GET /api/v1/cluster/summary

Returns an aggregate Kubernetes summary across all of your organization's agents combined (nodes and pods only, this endpoint doesn't cover Docker containers).

Response 200

{
  "totalNodes": 3,
  "readyNodes": 3,
  "totalPods": 24,
  "runningPods": 22,
  "pendingPods": 1,
  "failedPods": 1,
  "namespaces": 5
}

Instant metric query

GET /api/v1/metrics/instant

Runs a single-point-in-time query against the underlying time-series store, scoped to your organization automatically. This is a snapshot at the current moment, not a time range; see Range metric query below for historical data.

Query parameters

Parameter	Type	Description
`metric` (or `selector`)	string	A metric name with optional label matchers, e.g. `cpu_percent{container="web-app"}`. Only a single vector selector is accepted, full PromQL (functions, ranges, aggregation) is rejected.

Response 200

{
  "series": [
    { "metric": { "__name__": "cpu_percent", "container": "web-app" }, "value": 12.4 }
  ],
  "count": 1
}

Range metric query

GET /api/v1/metrics/range

Runs a PromQL range query over a time window, for building charts. Same organization scoping and single-vector-selector validation as the instant query above.

Query parameters

Parameter	Type	Description
`metric` (or `selector`)	string	Same rules as the instant query above.
`start` / `end`	unix seconds	Defaults to the last hour if omitted. Rejected with `400` if `end` is before `start`, or if the window exceeds 7 days.
`step`	Prometheus duration string	Defaults to `15s`.

The window is also clamped to your organization's configured retention (Settings → Usage & Limits), so if the whole requested range predates the retention cutoff, this returns an empty series rather than an error.

Response 200

{
  "series": [
    {
      "metric": { "__name__": "cpu_percent", "container": "web-app" },
      "values": [[1750000000, 11.8], [1750000015, 12.4]]
    }
  ],
  "count": 1
}