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

# JavaScript SDK: live logs and status

> Stream an application's live logs, status and system events with api.apps.realtime(), an async iterable that merges status frames and reconnects on its own.

`api.apps.realtime(appId, { signal })` opens a live stream of an app's logs, status and system events. It is an **async iterable**: consume it with `for await`.

Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them.

```typescript theme={"system"}
const controller = new AbortController();

for await (const event of api.apps.realtime(appId, { signal: controller.signal })) {
    if (event.event === "logs") {
        console.log(event.stream, event.line); // "stdout" | "stderr"
    } else if (event.event === "status") {
        console.log(event.status.cpu, event.status.ram); // always the full, merged state
    } else {
        console.log(event.event, event.data); // "system" or "error"
    }
}
```

## Events

Every event has `event`, `data` (the raw frame text) and `id`.

| `event` | Extra fields | Description |
| - | - | - |
| `logs` | `stream`, `line` | One log line. The first character of `data` tells the stream (`\u0001` stdout, `\u0002` stderr); the SDK strips it into `line` and sets `stream` to `"stdout"` or `"stderr"` |
| `status` | `status` | Live container metrics. The first frame is complete and the next ones only carry what changed: the SDK merges them, so `status` is always the full state |
| `system` | | Connection events such as `REALTIME_CONNECTING \| <id>`, `REALTIME_TIMEOUT` or `REALTIME_DISCONNECTED` |
| `error` | | An error code such as `CONTAINER_NOT_FOUND` |
| `message` | | A frame without an `event` name |

### The `status` object

| Field | Description |
| - | - |
| `cpu` | CPU usage (%) |
| `cpuLimit` | Number of CPU cores allocated |
| `ram` | `[usedMB, limitMB]` |
| `status` | Container state, e.g. `running` |
| `netIO` | Network `{ i, o }` totals, with `new` for the latest interval |
| `bIO` | Disk `{ i, o }` totals |
| `uptime` | Unix ms of the container start |

## Ending the stream

The loop ends on its own when:

* the server closes the connection cleanly (each connection lasts up to **10 minutes**);
* the server sends `REALTIME_DISCONNECTED`;
* you `break` out of the loop;
* you call `controller.abort()` (the loop just ends, it does not throw).

To keep watching past 10 minutes, open a new stream when the loop ends.

## Reconnection

A dropped connection, or the server handing reconnection to the client (`REALTIME_RECONNECT`), reopens the stream on its own:

* up to **3 times in a row**; any `logs` or `status` event resets the count;
* each reopen at least **5.5 s** after the previous open, to stay under the API's pace of one open per 5 seconds per app.

Past 3 failed reconnections, the loop throws a `SquareCloudAPIError` with `NETWORK_ERROR`.

## Limits and errors

* **5** concurrent connections per account and **30** per app, across all users. Going over is 429 `REALTIME_MAX_CONNECTIONS` or `REALTIME_MAX_CONNECTIONS_APP`.
* The HTTP status is checked before streaming, so these errors (and 404 for an unknown app) throw on the first iteration.
* The timeout only covers the open, until the response headers arrive. The stream itself has no timeout.

## Next steps

<CardGroup cols={3}>
  <Card title="Snapshots" icon="clock-rotate-left" href="/en/sdks/js/snapshots">
    Back up and restore apps and databases.
  </Card>

  <Card title="Realtime API reference" icon="code" href="/en/api-reference/endpoint/apps/realtime">
    The REST endpoint behind this stream.
  </Card>

  <Card title="Logs from the CLI" icon="terminal" href="/en/cli-reference/logs">
    The same stream from the terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.