Skip to main content
Snapshots are copies of an app’s or database’s storage. Apps and databases share the same four methods:
  • client.apps.snapshots: list(app_id), create(app_id), restore(app_id, name, version_id), restore_state(app_id)
  • client.databases.snapshots: list(database_id), create(database_id), restore(database_id, name, version_id), restore_state(database_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

When snapshot storage cannot answer, list() raises 503 SNAPSHOTS_UNAVAILABLE instead of returning an empty list: your snapshots are still stored, so try again in about 30 seconds.

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': ...}. An API key without the snapshots:read scope gets {'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. It waits for the restore (at least 120 s before timing out) and returns {'pending': False} when it is done. A restore that is not done after about 90 seconds keeps running: the API answers 202 SNAPSHOT_RESTORE_PROCESSING and the SDK returns {'pending': True}. Follow it with restore_state(id).
restore_state(id) reports the last restore of the app or database. It allows 30 calls a minute, so poll it every few seconds.
Never call restore() again to check on a pending restore: follow it with restore_state() instead.

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 the snapshots of all your apps ("applications", the default) or of all your databases ("databases", keyword-only). It needs an active plan and is limited to 3 calls a minute (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, starting or stopping the app or database, restarting the app and taking a snapshot are 409 RESTORE_IN_PROGRESS.
  • During maintenance, create() and restore() are 503 CLUSTER_MAINTENANCE_TRY_LATER: try again in a few minutes.

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.