Skip to main content
Snapshots are backups of an app’s or database’s storage. Apps and databases share the same three methods:
  • client.apps.snapshots: list(app_id), create(app_id), restore(app_id, name, version_id)
  • client.databases.snapshots: list(database_id), create(database_id), restore(database_id, name, version_id)
How many snapshots you can create per day depends on your plan (see Limits). Examples use the client from Creating the client. app_id is the id of one of your apps: client.account.me() lists them.

​
Listing snapshots

​
Creating a snapshot

create() waits for the snapshot (at least 120 s before timing out). A large snapshot may not finish in time: the API then answers 202 and the SDK returns {'pending': True}. The snapshot keeps generating and shows up in list() on its own, usually within 2 minutes. Otherwise it returns {'pending': False, 'url': ..., 'key': ...}.
Never call create() again to check on a pending snapshot: it starts a new one and counts against the plan’s daily snapshot quota. Poll list() instead.

​
Restoring a snapshot

restore(id, name, version_id) takes the name and version_id of a listed snapshot.

​
Downloading a snapshot

client.download_snapshot(url, dest) streams a snapshot file from its signed url (from list() or create()) to disk and returns the path it wrote. It does not call the API: the API key is never sent to the storage host. Nothing is buffered in memory.
  • dest is a file path, or a directory to keep the remote file name. A path ending in / is created as a directory.
  • The data goes to a .part file that is renamed when complete, so a failed download never overwrites an earlier file.
  • There is no timeout for the whole download: timeout bounds each read.
With AsyncSquareCloud, it is await client.download_snapshot(url, dest). An expired or invalid URL raises a SquareCloudAPIError with the storage host’s HTTP status and UNKNOWN_ERROR. A destination that cannot be written raises an OSError.

​
Account snapshots

client.account.snapshots(scope=None) lists every snapshot of the account, optionally only "applications" or "databases" (keyword-only). It needs an active plan and shares the network endpoints’ rate limit (429 RATE_LIMITED).

​
Limits

  • create() is limited to one call per 180 seconds and to a daily quota that depends on the plan: going over the quota is 429 DAILY_SNAPSHOTS_LIMIT_REACHED.
  • While a restore runs, deleting the app or starting the database is 403 RESTORE_IN_PROGRESS.

​
Next steps

Databases

Create and manage databases.

Snapshot API reference

The REST endpoints behind these methods.

Snapshots from the CLI

The same actions from the terminal.