WebSocket API

The KubeWatch Live Data service exposes a WebSocket endpoint for real-time streaming of container metrics, pod status changes, and alert events to the dashboard (or any custom client).

Connecting

wss://YOUR_KUBEWATCH_URL/ws?token=YOUR_JWT_TOKEN

Authentication is via JWT token passed as a query parameter. API keys are not supported for WebSocket connections, obtain a JWT first via POST /auth/login.

JavaScript example:

const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
const ws = new WebSocket(`wss://YOUR_KUBEWATCH_URL/ws?token=${token}`);

ws.addEventListener("open", () => {
  console.log("Connected to KubeWatch live stream");
});

ws.addEventListener("message", (event) => {
  const message = JSON.parse(event.data);
  console.log(message.type, message.data);
});

ws.addEventListener("close", (event) => {
  console.log("Disconnected:", event.code, event.reason);
});

Message format

All messages from the server are JSON objects with this shape:

{
  "type": "container.update",
  "agentId": "agent_abc123",
  "orgId": "org_xyz789",
  "timestamp": "2026-06-12T10:00:05Z",
  "data": {}
}

The data object shape depends on the type.

Event types

container.update

Emitted every push interval for each container with updated metrics.

{
  "type": "container.update",
  "agentId": "agent_abc123",
  "timestamp": "2026-06-12T10:00:05Z",
  "data": {
    "id": "container_xyz",
    "name": "web-app",
    "status": "running",
    "cpuPercent": 45.2,
    "memoryMB": 512,
    "networkRxBytes": 1048576,
    "networkTxBytes": 524288,
    "restartCount": 0
  }
}

pod.update

Emitted when a pod status changes or metrics are refreshed.

{
  "type": "pod.update",
  "agentId": "agent_abc123",
  "timestamp": "2026-06-12T10:00:05Z",
  "data": {
    "name": "web-app-7d9f8-xk2pq",
    "namespace": "default",
    "status": "Running",
    "restartCount": 0
  }
}

node.update

Emitted when node metrics are refreshed.

{
  "type": "node.update",
  "agentId": "agent_abc123",
  "timestamp": "2026-06-12T10:00:05Z",
  "data": {
    "name": "worker-01",
    "status": "Ready",
    "cpuUsedPercent": 42.1,
    "memoryUsedMB": 5120
  }
}

alert.fired

Emitted when an alert rule transitions to the firing state.

{
  "type": "alert.fired",
  "timestamp": "2026-06-12T10:05:00Z",
  "data": {
    "alertRuleId": "alert_rule_abc123",
    "ruleName": "High CPU on prod-web",
    "metric": "cpu_percent",
    "currentValue": 94.2,
    "threshold": 90,
    "containerName": "web-app",
    "agentId": "agent_abc123"
  }
}

alert.resolved

Emitted when a firing alert resolves (condition returns to normal).

{
  "type": "alert.resolved",
  "timestamp": "2026-06-12T10:20:00Z",
  "data": {
    "alertRuleId": "alert_rule_abc123",
    "ruleName": "High CPU on prod-web",
    "resolvedAt": "2026-06-12T10:20:00Z"
  }
}

Reconnection

The KubeWatch dashboard uses exponential backoff for automatic reconnection. Implement the same pattern in custom clients:

function connectWithBackoff() {
  let attempt = 0;
  const maxBackoff = 30000; // 30 seconds

  function connect() {
    const ws = new WebSocket(`wss://YOUR_KUBEWATCH_URL/ws?token=${getToken()}`);

    ws.addEventListener("open", () => {
      attempt = 0;
      console.log("Connected");
    });

    ws.addEventListener("close", (event) => {
      if (event.code === 1008) {
        refreshToken().then(connect);
        return;
      }
      const backoff = Math.min(1000 * Math.pow(2, attempt++), maxBackoff);
      console.log(`Reconnecting in ${backoff}ms (attempt ${attempt})`);
      setTimeout(connect, backoff);
    });

    return ws;
  }

  return connect();
}

Connection close codes