> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildpixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```js theme={null}
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

```js theme={null}
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](/builds/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.