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

# JavaScript SDK: manage applications

> Fetch, inspect and control your applications with @squarecloud/api: details, status, start, stop, restart, logs, metrics, domains, load balancers and deletion.

Every method on this page lives on `api.apps` and takes the app id first. An `appId` can also be the composite `<appId>-<workspaceId>` of an app shared through a [workspace](/en/sdks/js/workspaces).

```typescript theme={"system"}
import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!);
const appId = "abc123def456abc123def456";
```

To list your apps, use [`api.account.me()`](/en/sdks/js/client#account): its `applications` array has every app the key can see.

## Getting an application

```typescript theme={"system"}
const app = await api.apps.get(appId);

console.log(app.id, app.name, app.language, app.ram, app.cluster, app.created_at);
```

| Field | Type | Description |
| - | - | - |
| `id` | `string` | App id |
| `name` | `string` | Display name |
| `desc` | `string?` | Description |
| `owner` | `string` | Owner's user id |
| `cluster` | `string` | Cluster the app runs on |
| `ram` | `number` | Allocated RAM in MB |
| `language` | `string` | Runtime language |
| `domain` | `string \| null?` | Default `<subdomain>.squareweb.app` host; absent or `null` for non-web apps |
| `custom` | `string \| null?` | Custom domain; absent or `null` when none is set |
| `created_at` | `string` | Creation date (ISO 8601) |

## Status

`status(appId)` returns the live state with **formatted** values:

```typescript theme={"system"}
const status = await api.apps.status(appId);

console.log(status.status);  // e.g. "running", "exited"
console.log(status.running); // true
console.log(status.cpu);     // "0.5%"
console.log(status.ram);     // "120.4MB" (RAM in use)
console.log(status.storage, status.network.total, status.network.now);
console.log(status.uptime);  // Unix ms of the last start, null when stopped
```

Pass `{ raw: true }` to get **numbers** instead (`cpu` in %, `ram` in MB, `network.total` and `network.now` as `[in, out]` byte pairs):

```typescript theme={"system"}
const raw = await api.apps.status(appId, { raw: true });

console.log(raw.cpu, raw.ram, raw.network.total); // 0.5 120.4 [1024, 2048]
```

<Note>
  `uptime` is a **timestamp** (when the app started), not a duration. Use `Date.now() - status.uptime` for how long it has been up.
</Note>

### Status of every application

`statusAll()` returns one summary per app the key can see, in a single request. `cpu` and `ram` are only present while the app runs.

```typescript theme={"system"}
for (const { id, running, cpu, ram } of await api.apps.statusAll()) {
    console.log(id, running ? `${cpu} ${ram}` : "stopped");
}

// Only the apps of one workspace
const shared = await api.apps.statusAll({ workspaceId });
```

## Start, stop and restart

```typescript theme={"system"}
await api.apps.start(appId);
await api.apps.stop(appId);
await api.apps.restart(appId);
```

The server holds these calls open until the container acts, so they wait at least 120 s before timing out. When the platform refuses the action, the call throws a `SquareCloudAPIError` with status **409**, a `code` and an **empty** message:

| Code | Meaning |
| - | - |
| `CONTAINER_ALREADY_STARTED` | `start` on a running app |
| `CONTAINER_ALREADY_STOPPED` | `stop` on a stopped app |
| `CONTAINER_TEMPORARILY_SUSPENDED` | The app is suspended |
| `CONTAINER_NOT_FOUND` | The container does not exist on the cluster |
| `CONTAINER_INSUFFICIENT_DISK_SPACE` | Not enough disk to start |
| `CONTAINER_NETWORK_CONFLICT` | Network conflict on the cluster |
| `ACTION_FAILED` | The cluster could not perform the action |

"Already started" and "already stopped" are errors too. If they mean success for you, handle them:

```typescript theme={"system"}
import { SquareCloudAPIError } from "@squarecloud/api";

try {
    await api.apps.start(appId);
} catch (error) {
    if (!(error instanceof SquareCloudAPIError && error.code === "CONTAINER_ALREADY_STARTED")) {
        throw error;
    }
}
```

## Logs

`logs(appId)` returns the latest console output as one string (`""` when there is none).

```typescript theme={"system"}
console.log(await api.apps.logs(appId));
```

For a live stream of logs, use [Realtime](/en/sdks/js/realtime).

## Metrics

`metrics(appId)` returns the last 24 hours, one point every 5 minutes, **newest first**.

```typescript theme={"system"}
const [latest] = await api.apps.metrics(appId);

console.log(latest.date, latest.cpu, latest.ram, latest.net);
```

## Domains and load balancers

`domains()` lists the default and custom hostnames of every app. `loadBalancers()` lists the domains shared by several apps, with your plan's limit.

```typescript theme={"system"}
for (const { app_id, hostname, type } of await api.apps.domains()) {
    console.log(app_id, hostname, type); // type: "subdomain" | "custom"
}

const { limit, balancers } = await api.apps.loadBalancers();
for (const { hostname, apps } of balancers) {
    console.log(hostname, apps.map((app) => app.id));
}
```

To set a custom domain, see [Network](/en/sdks/js/network#custom-domain).

## Deleting an application

```typescript theme={"system"}
await api.apps.delete(appId);
```

<Warning>
  Deletion is permanent. Create a [snapshot](/en/sdks/js/snapshots) first if you may need the files again.
</Warning>

## Next steps

<CardGroup cols={3}>
  <Card title="Commit and upload" icon="upload" href="/en/sdks/js/commit_and_upload">
    Create an app from a zip or send files to one.
  </Card>

  <Card title="Application API reference" icon="code" href="/en/api-reference/endpoint/apps/info">
    The REST endpoints behind these methods.
  </Card>

  <Card title="Manage apps from the CLI" icon="terminal" href="/en/cli-reference/apps">
    The same actions from the terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.