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

# Stream real-time logs and metrics (SSE)

> Open a Server-Sent Events stream with GET /v2/apps/{app_id}/realtime for live logs, metrics, status and deploy progress. A connection lasts 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>

Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes).

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 short 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 it was, `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 }` (`cpuLimit` is the number of CPU cores allocated; `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={"system"}
  event: system
  data: REALTIME_CONNECTING | abc123-1716000000000-deadbeef

  event: status
  data: {"cpu":12.5,"cpuLimit":1,"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. |

## Related

* CLI: [`squarecloud app realtime`](/en/cli-reference/logs#squarecloud-app-realtime)
* SDKs: [`api.apps.realtime()`](/en/sdks/js/realtime) (JavaScript), [`client.apps.realtime()`](/en/sdks/py/realtime) (Python), [`c.Apps.Realtime()`](/en/sdks/go/realtime) (Go)


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