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

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