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

# Logs en tiempo real

> Establece una conexión de Server-Sent Events (SSE) para recibir el feed en tiempo real de tu aplicación (logs, métricas en vivo, estado, progreso del deploy). Al conectar, se envían las 200 líneas de log más recientes, seguidas de las nuevas actualizaciones. La conexión puede mantenerse hasta 10 minutos.

<Info>El API Playground está deshabilitado para este endpoint debido a la naturaleza de las conexiones SSE, que no son compatibles de forma universal con los navegadores.</Info>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La clave de API de tu cuenta. Puedes encontrarla en la [configuración de tu cuenta](https://squarecloud.app/es/account/security).
</ParamField>

### Parámetros

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  El ID de la aplicación cuyos logs quieres monitorear. Este ID se puede encontrar en la URL del panel de administración de tu aplicación.
</ParamField>

### Respuesta

<ResponseField name="status" type="string">
  Indica si la llamada fue exitosa. `success` si fue exitosa, `error` si no.
</ResponseField>

En caso de fallo, la respuesta incluirá un campo `code` junto con el estado de error, detallando la causa.

Si la solicitud es exitosa, la respuesta será un stream `text/event-stream` que contiene el feed en tiempo real de la aplicación.

Cada conexión dura hasta **10 minutos**. Cada cuenta puede mantener **5 conexiones concurrentes en tiempo real** (`REALTIME_MAX_CONNECTIONS`) y cada aplicación **30 entre todos los usuarios** (`REALTIME_MAX_CONNECTIONS_APP`); superar cualquiera de los dos devuelve `429`.

### Estructura de los Server-Sent Events (SSE)

La respuesta es un stream continuo en formato `text/event-stream`. Cada mensaje se compone de un campo `event` y un campo `data`. Las estructuras varían según el evento, así que analiza los payloads de forma defensiva.

#### Tipos de evento

* `system`: Señales a nivel de protocolo. La línea `data` es un único código en mayúsculas: `REALTIME_CONNECTING | <sseId>` al conectar, y luego cualquiera de `REALTIME_TIMEOUT`, `REALTIME_DISCONNECTED`, `REALTIME_RECONNECT` o `REALTIME_ERROR`.
* `logs`: Una única línea de log cuyo **primer carácter es un byte de identificación del stream**: `\x01` (stdout) o `\x02` (stderr). Lee `data.charCodeAt(0)` (1 = stdout, 2 = stderr) y luego `data.slice(1)` para el texto. Una línea sin ese byte de prefijo es stdout.
* `status`: Métricas del contenedor en vivo como una cadena JSON, aproximadamente un frame por segundo. El **primer frame** de cada (re)conexión es completo: `{ cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime }` (`uptime` es el tiempo de inicio en ms epoch; `netIO.new` son bytes por segundo). **Cada frame posterior es reducido**, y solo contiene `{ cpu, ram, netIO, bIO }`: combina cada uno con el último frame completo, conservando el `cpuLimit`, `status` y `uptime` anteriores. Mientras este stream esté abierto, prefiérelo antes que sondear `GET /v2/apps/{app_id}/status`, que puede estar desactualizado hasta cerca de un minuto para una aplicación con un stream en tiempo real abierto.
* `error`: Contiene un código de error como `CONTAINER_NOT_FOUND`.

En el ejemplo de abajo, `\x01` / `\x02` representan los bytes de prefijo crudos de stdout / stderr.

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