Skip to main content
Every operation on this page starts by obtaining an Application instance: 
import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);
const app = await api.applications.fetch("abc123def456abc123def456");
api.applications.fetch(id) returns an Application. When the app has a website domain bound to it, it is returned as a WebsiteApplication — refine the type at runtime with app.isWebsite() before using .network (see Network).

​
Application properties

PropertyTypeDescription
idstringApplication ID (24 hex chars)
namestringDisplay name
descriptionstring?Description from squarecloud.app
urlstringWeb dashboard URL
ramnumberAllocated RAM in MB
clusterstringCluster the app runs on
languagestringjavascript | typescript | python | java | elixir | rust | go | php | dotnet | static
domainstring | nullDefault <subdomain>.squareweb.app host (null for non-web apps)
customstring | nullCustom domain bound to the app, when configured
createdAtDateCreation date
In v4, app.custom is null when no custom domain is set (was undefined in v3).

​
Getting the application status

app.getStatus() returns an ApplicationStatus instance with the live runtime state. 
const status = await app.getStatus();

console.log(status.status);          // "running" | "starting" | "restarting" | "exited" | "created" | "deleting"
console.log(status.running);         // boolean
console.log(status.usage.cpu);       // "0.22%"
console.log(status.usage.ram);       // "70MB"
console.log(status.usage.network);   // { total: "0 KB ↑ 0 KB ↓", now: "0 KB ↑ 0 KB ↓" }
console.log(status.usage.storage);   // "0B"
console.log(status.uptime);          // Date | undefined
console.log(status.uptimeTimestamp); // number | undefined

​
Summary status for every application

To avoid one request per app, call api.applications.statusAll(): 
const list = await api.applications.statusAll();

for (const summary of list) {
    console.log(`${summary.applicationId} → running=${summary.running}`);
    if (summary.running) {
        console.log(`  cpu=${summary.usage.cpu}, ram=${summary.usage.ram}`);
    }

    // Promote a summary to the full status with .fetch()
    const full = await summary.fetch();
    console.log(full.uptime);
}

​
Getting the logs

app.getLogs() returns the most recent log output as a string. 
const logs = await app.getLogs();
console.log(logs);

​
Getting metrics

app.getMetrics() returns the last 24 hours of CPU, RAM and network samples (up to 288 points, one every 5 minutes). 
const metrics = await app.getMetrics();

console.log(metrics.length, "data points");
console.log(metrics[0]);
// { timestamp: 1717084800000, cpu: 12.3, ram: 187, network: { ... } }
getMetrics() requires the application to have at least 512MB of RAM allocated.

​
Real-time event stream

app.realtime() opens a Server-Sent Events stream. See the dedicated Realtime page for a full example.

​
Lifecycle

All lifecycle methods resolve to boolean (true on success). 
await app.start();
await app.restart();
await app.stop();

​
Deleting an application

app.delete() permanently removes the application. Unless you have a snapshot, the data cannot be recovered.
const deleted = await app.delete();
console.log(deleted); // true | false

​
Refreshing the application data

app.fetch() refetches the application from the API and returns a brand-new Application instance. Use it when you suspect the cached data is stale. 
const fresh = await app.fetch();