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

# Echtzeit-Logs

> Baut eine Server-Sent-Events-Verbindung (SSE) auf, um den Echtzeit-Feed deiner Anwendung zu empfangen (Logs, Live-Metriken, Status, Deploy-Fortschritt). Beim Verbindungsaufbau werden die 200 aktuellsten Log-Zeilen gesendet, gefolgt von neuen Aktualisierungen. Die Verbindung kann bis zu 10 Minuten aufrechterhalten werden.

<Info>Der API-Playground ist für diesen Endpoint deaktiviert, da SSE-Verbindungen ihrer Natur nach nicht von allen Browsern unterstützt werden.</Info>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  Der API-Schlüssel für Ihr Konto. Sie finden ihn in Ihren [Kontoeinstellungen](https://squarecloud.app/de/account/security).
</ParamField>

### Parameter

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  Die ID der Anwendung, deren Logs du überwachen möchtest. Diese ID findest du in der URL des Verwaltungspanels deiner Anwendung.
</ParamField>

### Antwort

<ResponseField name="status" type="string">
  Gibt an, ob der Aufruf erfolgreich war. `success` bei Erfolg, `error` andernfalls.
</ResponseField>

Im Fehlerfall enthält die Antwort ein Feld `code` zusätzlich zum Fehlerstatus, das die Ursache erläutert.

Ist die Anfrage erfolgreich, ist die Antwort ein `text/event-stream`-Stream, der den Echtzeit-Feed der Anwendung enthält.

Jede Verbindung dauert bis zu **10 Minuten**. Jedes Konto kann **5 gleichzeitige Echtzeit-Verbindungen** halten (`REALTIME_MAX_CONNECTIONS`) und jede Anwendung **30 über alle Nutzer hinweg** (`REALTIME_MAX_CONNECTIONS_APP`); wird eines der beiden Limits überschritten, wird `429` zurückgegeben.

### Struktur der Server-Sent Events (SSE)

Die Antwort ist ein kontinuierlicher Stream im Format `text/event-stream`. Jede Nachricht besteht aus einem Feld `event` und einem Feld `data`. Die Formen variieren je nach Event, parse die Payloads daher defensiv.

#### Event-Typen

* `system`: Signale auf Protokollebene. Die `data`-Zeile ist ein einzelner Code in Großbuchstaben: `REALTIME_CONNECTING | <sseId>` beim Verbindungsaufbau, danach einer von `REALTIME_TIMEOUT`, `REALTIME_DISCONNECTED`, `REALTIME_RECONNECT` oder `REALTIME_ERROR`.
* `logs`: Eine einzelne Log-Zeile, deren **erstes Zeichen ein Stream-ID-Byte ist**: `\x01` (stdout) oder `\x02` (stderr). Lies `data.charCodeAt(0)` (1 = stdout, 2 = stderr), dann `data.slice(1)` für den Text. Eine Zeile ohne dieses Präfix-Byte ist stdout.
* `status`: Live-Container-Metriken als JSON-String, etwa ein Frame pro Sekunde. Der **erste Frame** jeder (Wieder-)Verbindung ist vollständig: `{ cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime }` (`uptime` ist die Startzeit als Epoch-ms; `netIO.new` sind Bytes pro Sekunde). **Jeder spätere Frame ist schlank** und trägt nur `{ cpu, ram, netIO, bIO }` — führe jeden mit dem letzten vollständigen Frame zusammen und behalte dabei die vorherigen Werte von `cpuLimit`, `status` und `uptime`. Solange dieser Stream offen ist, bevorzuge ihn gegenüber dem Polling von `GET /v2/apps/{app_id}/status`, das bei einer Anwendung mit offenem Echtzeit-Stream bis zu etwa einer Minute veraltet sein kann.
* `error`: Trägt einen Fehlercode wie `CONTAINER_NOT_FOUND`.

Im folgenden Beispiel stehen `\x01` / `\x02` für die rohen stdout-/stderr-Präfix-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>