> ## 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.

# Real-time Logs

> Establish a Server-Sent Events (SSE) connection to receive your application's realtime feed (logs, live metrics, status, deploy progress). Upon connection, the 200 most recent log lines are sent, followed by new updates. The connection can be maintained for up to 10 minutes.

<Info>The API Playground is disabled for this endpoint due to the nature of SSE connections, which are not universally supported by browsers.</Info>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

Use this endpoint whenever you need a live view of an application instead of polling: watching a deploy progress, tailing logs as they are written, or driving a dashboard's CPU/RAM graph without hammering [Get Application Status](/en/api-reference/endpoint/apps/status) or [Get Application Logs](/en/api-reference/endpoint/apps/logs) on a timer. It replaces both for the duration of the connection.

Internally, opening a connection here dials a single upstream stream on the application's cluster and relays it back over SSE, with one transparent internal reconnect if that upstream drops. Because each open connection holds a socket for up to 10 minutes, opens are rate limited separately from the concurrent-connection caps described below: 1 open every 5 seconds per (user, application), and 20 opens every 10 seconds per user across all applications, with a 30-second cooldown after that.

### Parameters

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  The ID of the application whose logs you want to monitor. This ID can be found in the URL of your application's management panel.
</ParamField>

### Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful.. `success` if successful, `error` if not.
</ResponseField>

In case of failure, the response will include a `code` field along with the error status, detailing the cause.

If the request is successful, the response will be a `text/event-stream` stream containing the application's realtime feed.

Each connection lasts up to **10 minutes**. Each account may hold **5 concurrent realtime connections** (`REALTIME_MAX_CONNECTIONS`) and each application **30 across all users** (`REALTIME_MAX_CONNECTIONS_APP`); exceeding either returns `429`.

### Server-Sent Events (SSE) Structure

The response is a continuous stream in `text/event-stream` format. Each message is composed of an `event` field and a `data` field. Shapes vary by event, so parse payloads defensively.

#### Event Types

* `system`: Protocol-level signals. The `data` line is a single uppercase code: `REALTIME_CONNECTING | <sseId>` on connect, then any of `REALTIME_TIMEOUT`, `REALTIME_DISCONNECTED`, `REALTIME_RECONNECT`, or `REALTIME_ERROR`.
* `logs`: A single log line whose **first character is a stream-id byte**: `\x01` (stdout) or `\x02` (stderr). Read `data.charCodeAt(0)` (1 = stdout, 2 = stderr), then `data.slice(1)` for the text. A line without that prefix byte is stdout.
* `status`: Live container metrics as a JSON string, about one frame per second. The **first frame** of each (re)connection is complete: `{ cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime }` (`uptime` is the start time as epoch ms; `netIO.new` is bytes per second). **Every later frame is lean**, carrying only `{ cpu, ram, netIO, bIO }` — merge each onto the last complete frame, keeping the previous `cpuLimit`, `status`, and `uptime`. While this stream is open, prefer it over polling `GET /v2/apps/{app_id}/status`, which can be up to about a minute stale for an app with an open realtime stream.
* `error`: Carries an error code such as `CONTAINER_NOT_FOUND`.

In the example below, `\x01` / `\x02` stand for the raw stdout / stderr prefix bytes.

<CodeGroup>
  ```text Stream example theme={null}
  event: system
  data: REALTIME_CONNECTING | abc123-1716000000000-deadbeef

  event: status
  data: {"cpu":12.5,"cpuLimit":100,"ram":[128,512],"status":"running","netIO":{"i":2048,"o":4096,"new":{"i":64,"o":128}},"bIO":{"i":0,"o":0},"uptime":1716000000000}

  event: status
  data: {"cpu":13.1,"ram":[131,512],"netIO":{"i":2176,"o":4288,"new":{"i":72,"o":140}},"bIO":{"i":0,"o":0}}

  event: logs
  data: \x01Server listening on :3000

  event: logs
  data: \x02Error: connect ECONNREFUSED
  ```
</CodeGroup>

### Common errors

| Code                           | HTTP | Meaning                                                                               |
| ------------------------------ | ---- | ------------------------------------------------------------------------------------- |
| `REALTIME_MAX_CONNECTIONS`     | 429  | The caller already has 5 concurrent realtime connections open.                        |
| `REALTIME_MAX_CONNECTIONS_APP` | 429  | The application already has 30 concurrent realtime connections open across all users. |