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

# Snapshots

> List, create, download and restore application snapshots.

<Info>
  `app.backup` / `app.backups` and the `Backup` class have been removed. Use `app.snapshots` (the [`SnapshotsModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/snapshots.ts)), whose entries are instances of `Snapshot` (`DatabaseSnapshot` for database snapshots).
</Info>

`app.snapshots` exposes the [`SnapshotsModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/snapshots.ts).

```typescript theme={null}
const app = await api.applications.fetch("abc123def456abc123def456");
app.snapshots; // SnapshotsModule
```

## Rate limits

* `app.snapshots.list()` results are cached server-side for **30 minutes**.
* `app.snapshots.create()` (and the database equivalent) is limited to **1 request every 5 seconds per user** and **1 request every 3 minutes per resource** (application or database).
* Each plan also has a **daily snapshot quota**. Once it's exhausted, creation fails with a `429` and `code: "DAILY_SNAPSHOTS_LIMIT_REACHED"` — distinct from the generic `KEEP_CALM` short-rate-limit error.

```typescript theme={null}
try {
    await app.snapshots.create();
} catch (error) {
    if (error.code === "DAILY_SNAPSHOTS_LIMIT_REACHED") {
        console.log("Daily snapshot quota reached for this plan");
    }
}
```

## Listing snapshots

`app.snapshots.list()` returns an array of `Snapshot` instances.

```typescript theme={null}
const snapshots = await app.snapshots.list();

for (const snap of snapshots) {
    console.log(snap.url);          // signed download URL (valid for 30 days)
    console.log(snap.size);         // bytes
    console.log(snap.modifiedAt);   // Date
    console.log(snap.key);          // signed query string
}
```

Each snapshot can be downloaded directly:

```typescript theme={null}
const buffer = await snapshots[0].download();
```

## Creating a new snapshot

`app.snapshots.create()` triggers a fresh snapshot and returns the signed URL and key.

```typescript theme={null}
const fresh = await app.snapshots.create();
console.log(fresh.url); // valid for 30 days
console.log(fresh.key);
```

## Download in one step

`app.snapshots.download()` creates a snapshot and downloads it as a `Buffer`.

```typescript theme={null}
import { writeFile } from "node:fs/promises";

const buffer = await app.snapshots.download();
await writeFile("./backup.zip", buffer);
```

## Restoring from a snapshot

`app.snapshots.restore({ snapshotId, versionId })` rolls the application back to a previous snapshot version.

```typescript theme={null}
await app.snapshots.restore({
    snapshotId: "00000000-0000-4000-8000-000000000000",
    versionId: "abc123def4567890",
});
```

| Field        | Type     | Description                             |
| ------------ | -------- | --------------------------------------- |
| `snapshotId` | `string` | Snapshot identifier (UUID v4)           |
| `versionId`  | `string` | Version identifier returned by `list()` |

## Listing snapshots account-wide

`api.user.snapshots(scope?)` returns every snapshot you own across all your applications or databases. `scope` defaults to `"applications"`.

```typescript theme={null}
const appSnapshots = await api.user.snapshots(); // scope defaults to "applications"
const dbSnapshots  = await api.user.snapshots("databases");
```

<Note>
  `api.user.snapshots()` requires an active paid plan. Accounts without one get a `402` with `code: "UPGRADE_REQUIRED"`.
</Note>