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: 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): 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
}