---
title: "Open a Server-Sent Events stream of realtime application events"
method: GET
path: "/v2/apps/{appId}/realtime"
tags: ["Lifecycle"]
---

# Open a Server-Sent Events stream of realtime application events

`GET /v2/apps/{appId}/realtime`

Opens an SSE connection that streams the application's realtime feed (deploy progress, status changes, live metrics, log lines) for up to 10 minutes per connection. Each user is limited to 5 concurrent realtime connections, and each application to 30 across all users.

The stream emits these event types:

- `event: system` carries 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`, `REALTIME_ERROR`.
- `event: logs` is a single log line whose FIRST character is a stream-id byte: `\u0001` (stdout) or `\u0002` (stderr). Read `data.charCodeAt(0)` (1 = stdout, 2 = stderr), then `data.slice(1)` for the line text. A line without that prefix byte is stdout.
- `event: status` carries 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 StartedAt as epoch ms; `netIO.new` is bytes per second). Every later frame is LEAN, carrying only the live fields `{ cpu, ram, netIO, bIO }`: the run-constant fields (`cpuLimit`, `status`, `uptime`) are omitted, so MERGE each lean frame onto the last full frame and keep the previous values for the missing fields. While this stream is open, prefer it over polling `GET /v2/apps/:appId/status`, which can be up to about a minute stale for an application with an open realtime stream.
- `event: error` carries an error code such as `CONTAINER_NOT_FOUND`.

Shapes vary by event, so parse structured payloads (the `status` JSON and most `system`/app messages) defensively and merge successive `status` frames.

## Path parameters

- `appId` string, required

## Response `200`

SSE stream established. Content type is `text/event-stream`.

## Other responses

- `401` — The Authorization header is missing, malformed, or the credentials are not valid.
- `404` — The target application could not be found, or the caller is not a member of the workspace.
- `429` — The user already has 5 concurrent realtime connections open (`REALTIME_MAX_CONNECTIONS`), or the application already has 30 across all users (`REALTIME_MAX_CONNECTIONS_APP`).
- `500` — An unexpected error occurred while processing the request.

---

[API](https://skmtc.dev/squarecloud/apis/square-cloud-api.md) · [All operations](https://skmtc.dev/squarecloud/apis/square-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/squarecloud/square-cloud-api/revisions/54b7733a6b95/schema)