Stream real-time logs and metrics (SSE)

curl --request GET \
  --url https://api.squarecloud.app/v2/apps/{app_id}/realtime \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/realtime', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/realtime",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/realtime"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/realtime")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "status": "<string>"
}

The API Playground is disabled for this endpoint due to the nature of SSE connections, which are not universally supported by browsers.

string

required

The API key for your account. You can find this in your account settings.

Requires an API key with the apps:read scope. 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 or Get Application 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

string

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.

Response

string

Indicates whether the call was successful: success if it was, error if not.

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.

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

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.

CLI: squarecloud app realtime
SDKs: api.apps.realtime() (JavaScript), client.apps.realtime() (Python), c.Apps.Realtime() (Go)

Stream real-time logs and metrics (SSE)

curl --request GET \
  --url https://api.squarecloud.app/v2/apps/{app_id}/realtime \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/realtime', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/realtime",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/realtime"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/realtime")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "status": "<string>"
}

Get started

Account

Applications

Databases

Workspaces

AI

Stream real-time logs and metrics (SSE)

Parameters

Response

Server-Sent Events (SSE) Structure

Event Types

Common errors

​Parameters

​Response

​Server-Sent Events (SSE) Structure

​Event Types

​Common errors

​Related

Parameters

Response

Server-Sent Events (SSE) Structure

Event Types

Common errors

Related