Real-time logs (Socket.IO)

Live build status and streamed log lines.

For live monitoring — build status changes and streamed log lines — use the Socket.IO channel. Polling the REST API works but wastes requests and adds latency.

Connecting

import { io } from "socket.io-client";

const socket = io("https://api.buildpixel.io", {
  auth: { token: "<your token>" },
  transports: ["websocket"],
});

socket.on("connect", () => {
  console.log("connected");
});

The auth.token is your standard API token. The token’s permissions determine which builds you can subscribe to.

Joining a build’s room

socket.emit("join:build", { buildId: "65f..." });

socket.on("build:status", ({ status }) => {
  console.log("status:", status);
});

socket.on("build:log", ({ level, message, timestamp }) => {
  console.log(`[${level}] ${message}`);
});

// Later, when you're done:
socket.emit("leave:build", { buildId: "65f..." });
socket.disconnect();

Events

Event	Payload
build:status	{ buildId, status, ... } — fires when the build’s status changes
build:log	{ buildId, timestamp, level, message } — fires for each line of build output

status matches the values in Build statuses: pending, running, complete, failed, superseded.

level is info, warn, or error.

Disconnect handling

The Socket.IO client library reconnects automatically. After reconnect, re-emit join:build for any rooms you were in.

Closing the connection

Always disconnect cleanly when you’re done — especially in serverless environments where lingering connections cost money.