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

# Python 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 `client.apps` and takes the app id first. An `app_id` can also be the composite `<appId>-<workspaceId>` of an app shared through a [workspace](/en/sdks/py/workspaces).

```python theme={"system"}
import os

from squarecloud import SquareCloud

client = SquareCloud(os.environ["SQUARECLOUD_API_KEY"])
app_id = "abc123def456abc123def456"
```

With `AsyncSquareCloud`, every call below is the same with `await` in front.

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

## Getting an application

```python theme={"system"}
app = client.apps.get(app_id)

print(app["id"], app["name"], app["language"], app["ram"], app["cluster"], app["created_at"])
```

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

Optional fields may be missing from the dict: read them with `app.get("domain")`.

## Status

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

```python theme={"system"}
status = client.apps.status(app_id)

print(status["status"])   # e.g. "running", "exited"
print(status["running"])  # True
print(status["cpu"])      # "0.5%"
print(status["ram"])      # "120.4MB" (RAM in use)
print(status["storage"], status["network"]["total"], status["network"]["now"])
print(status["uptime"])   # Unix ms of the last start, None when stopped
```

Pass `raw=True` to get **numbers** instead (`cpu` in %, `ram` in MB, `network["total"]` and `network["now"]` as `[in, out]` byte pairs):

```python theme={"system"}
raw = client.apps.status(app_id, raw=True)

print(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 `time.time() * 1000 - status["uptime"]` for how long it has been up, in ms.
</Note>

### Status of every application

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

```python theme={"system"}
for item in client.apps.status_all():
    print(item["id"], f"{item['cpu']} {item['ram']}" if item["running"] else "stopped")

# Only the apps of one workspace
shared = client.apps.status_all(workspace_id=workspace_id)
```

## Start, stop and restart

```python theme={"system"}
client.apps.start(app_id)
client.apps.stop(app_id)
client.apps.restart(app_id)
```

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

```python theme={"system"}
from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as error:
    if error.code != "CONTAINER_ALREADY_STARTED":
        raise
```

## Logs

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

```python theme={"system"}
print(client.apps.logs(app_id))
```

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

## Metrics

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

```python theme={"system"}
latest = client.apps.metrics(app_id)[0]

print(latest["date"], latest["cpu"], latest["ram"], latest["net"])
```

## Domains and load balancers

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

```python theme={"system"}
for domain in client.apps.domains():
    print(domain["app_id"], domain["hostname"], domain["type"])  # type: "subdomain" | "custom"

balancers = client.apps.load_balancers()
print(balancers["limit"])
for balancer in balancers["balancers"]:
    print(balancer["hostname"], [app["id"] for app in balancer["apps"]])
```

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

## Deleting an application

```python theme={"system"}
client.apps.delete(app_id)
```

<Warning>
  Deletion is permanent. Create a [snapshot](/en/sdks/py/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/py/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.