Snapshots and restores in the background
Taking and restoring a snapshot no longer has to fit inside one request. Large applications and databases now work, and you can follow each operation until it ends.- Restore. Restoring a snapshot answers
202right away with ajob_id, and the restore runs in the background. An application is rebuilt and restarted when it finishes. While a restore runs, writes to the resource answer409 RESTORE_IN_PROGRESS; reading and deleting it are still allowed. A database that fails to load the data keeps the data it had. - Create a snapshot. It answers
201with the snapshot when it is ready within 90 seconds, or202with ajob_idwhen it takes longer. The snapshot shows up in the list when it is ready. - Create an application or a database from a snapshot. It answers
202(before,201) with arestore_job_id, with no size limit beyond the new resource’s storage (before, 100 MB for an application). If the restore fails, an application created from code is deleted, while a database and an application that runs a custom Docker image are kept as they are, so nothing you wrote is lost. - Not enough space. A snapshot that does not fit in the target’s storage is refused before anything changes with
SNAPSHOT_EXCEEDS_STORAGE, and for a database the answer says the smallest memory size that fits it. - A snapshot that does not match what was recorded when it was taken is refused with
SNAPSHOT_CORRUPTED, and nothing changes. - While an application is being snapshotted, deploys, rollbacks, restarts, starts, stops, environment variable changes, restores and the file manager’s writes wait: they answer
409 OPERATION_IN_PROGRESS, and you can try again in a few moments.
API
- List Snapshot Jobs (
GET /v1/users/{id}/snapshots/jobs) and Get Snapshot Job (GET /v1/users/{id}/snapshots/jobs/{job_id}) follow a snapshot or a restore until itsstatusisready,skippedorfailed, with thereasonwhen it fails. Both use thesnapshots:readscope. The list takeslimitfrom 1 to 50 (default 10; a value outside that range answers400 VALIDATION_ERROR), andscopeis optional when you read a single job. - Restore Snapshot answers
202withresponse.job_id. Themessageof the old answer is gone. - Create Stack Snapshot answers
202too, with theidof the stack snapshot and one snapshot job per member (response.jobs), databases first; before, it waited for every member and could be cut off on a large stack. Each member is a regular manual snapshot, and the quota and the checks of all of them are made before the202. List Stack Snapshots shows the stack snapshot aspendingand thenready(status), withsnapshot_id: nulland thejob_idof each member while it ispending; a stack snapshot with a failed member is not listed, and the ones that succeeded stay as regular snapshots. Apendingstack snapshot cannot be restored (409 OPERATION_IN_PROGRESS), and a second one cannot start while one is running. - Restore Stack Snapshot now answers
202too, with one job per member (response.jobs, each withresource_id,resource_type,job_idand, when it applies,warning). The members are restored in order, databases first; follow each job on Get Snapshot Job. If a member fails, the ones after it are not restored and their jobs fail withSTACK_RESTORE_MEMBER_FAILED. The old answer, which waited for every member, is gone. - Snapshots in the list now carry
origin(manualorautomatic). Snapshot jobs carry the sameorigin, absent on restore jobs.skippedis the status of a job that did nothing because the resource is gone or, for a database, stopped. restore_job_id(always present,nullwhen there is no restore) in the status of applications and databases (Application Status, All Applications Status, Database Status and All Databases Status): it is set while a restore of the resource is queued or running, and you follow it on Get Snapshot Job. While it is set, the application status does not carryinstalling.daily_backupsin the plan features andauthor_idin the snapshot were removed (author_idwas alwaysnull). Usedaily_app_backupsanddaily_database_backupsfor the plan, andoriginto tell what took a snapshot.- A snapshot job that failed now carries the
detailsof itsreason(for example the space needed and available forSNAPSHOT_EXCEEDS_STORAGE), a restore job carries thesnapshot_idit restores, and asnapshotjob that isreadyalways has thesnapshot_idit produced. - A resource that is not found now answers
404(APP_NOT_FOUND,DATABASE_NOT_FOUNDorIMAGE_NOT_FOUND) instead of403 ACCESS_DENIED.ACCESS_DENIEDstays for a workspace member without the permission for the action. Downloading a snapshot that was not found answers404 SNAPSHOT_NOT_FOUND(403stays only for a workspace member without permission), and the snapshot jobs of a resource that does not exist come back as an empty list. Workspaces follow the same rule: a workspace that is not found answers404 WORKSPACE_NOT_FOUNDinstead of403 WORKSPACE_PERMISSION_DENIED, which now only means a member whose role lacks the permission. WORKSPACE_INVITES_DISABLEDwas removed from the error codes and is no longer returned. Inviting by email an account that turned offworkspace_invites_enablednow answers like any other invite: it stays pending and no email is sent, so the answer does not reveal whether the email has an account. The setting only controls whether the account receives the invite email.- New error codes:
STACK_RESTORE_MEMBER_FAILED,RESTORE_IN_PROGRESS,SNAPSHOT_EXCEEDS_STORAGE,SNAPSHOT_CORRUPTED,SNAPSHOT_TIMEOUTandDATABASE_NOT_READY. See Error Codes. - On a template update, the
snapshotandrollbacksteps of the deploy job carryjobs(resource_id,resource_type,job_id) with the snapshot or restore job of each resource, so you can follow the progress on Get Snapshot Job.
Updated clients
The SDKs, the CLI, the MCP server and the VS Code extension follow the new behavior.- SDKs (JavaScript, Python and Go).
restoreanswers with thejob_idof the restore, and each SDK can follow a job until it ends (snapshotJobs.wait,snapshot_jobs.waitandSnapshotJobs.Wait), and there are helpers that do both steps (snapshots.createAndWait,stacks.snapshots.createAndWaitandrestoreAndWait, with the same names in snake_case in Python and in Go style in Go).apps.downloadtakes a manual snapshot, waits for it and downloads it, and needssnapshots:writeandsnapshots:read. A snapshot that takes longer is followed to the end, and creating an application or a database from a snapshot returns therestore_job_id. Downloads can also be streamed straight to a file with constant memory, whatever the size:snapshots.downloadToFile,snapshots.downloadStream,apps.downloadToFileandapps.downloadStreamin JavaScript,download_to_fileanddownload_streamin Python, andSnapshots.DownloadToFileandApps.DownloadToFilein Go. - CLI.
vertra snapshot restorenow waits for the restore to end by default (use--no-waitto get thejob_idright away). The newvertra snapshot jobshows a snapshot or restore job andvertra snapshot jobslists them.vertra app downloadkeeps its name: it takes a manual snapshot, waits for it and downloads the ZIP (it counts in the manual snapshot quota and needssnapshots:writeandsnapshots:read). Downloads are written to the file as the bytes arrive. - MCP.
restore_snapshotanswers with ajob_id, andcreate_snapshotanswers{ status: "accepted", job_id }when it takes longer. The newlist_snapshot_jobstool lists the jobs of a resource, andget_snapshot_jobfollows one job (it needs thejob_id).download_appkeeps its name: it takes a manual snapshot, waits for it and downloads it.create_appandcreate_databaseaccept asnapshot_id.download_appanddownload_snapshotwrite the file as it arrives too. - VS Code extension. Restoring shows its progress while it waits for the job to start and run.
Download a project of any size
A project of any size can be downloaded, with no 300 MB limit: you take a manual snapshot and download it. The snapshot appears in your list, uses the manual snapshot quota and is kept for 30 days.- Create Snapshot (
POST /v1/users/{id}/snapshots?scope=applications) answers201with the snapshot, or202with ajob_id. - After a
202, follow the job on Get Snapshot Job until itsstatusisready; it brings thesnapshot_id. - Download Snapshot (
GET /v1/users/{id}/snapshots/{snapshot_id}/download?scope=applications) returns the ZIP.
DOWNLOAD_TOO_LARGEis no longer returned when downloading an application. For one file, the file manager still reads it (GET /v1/apps/{id}/files/content).- An account without an active plan cannot take new snapshots, but it can still list and download the snapshots it has, including the one the platform kept before removing a project.
Changes that can break your integration
GET /v1/apps/{id}/downloadwas removed. It now answers404. Use the three steps above. A key that only hasapps:filesno longer downloads the project: it needssnapshots:writeto create the snapshot andsnapshots:readto download it (403 API_KEY_SCOPE_DENIED, withdetails.requiredset tosnapshots:read). Thedownload_idof the old answer is gone with it. SDKs, CLI, MCP and extension versions that call the old route must be updated.- Reset Database answers
{ "response": { "status": "success" } }(before, the string"success"). - Creating an application or a database from a snapshot answers
202(before,201), with the same body and therestore_job_id. warningmoved to each item of a stack restore. In Restore Stack Snapshot,IMAGE_VERSION_NOT_FOUNDnow comes inresponse.jobs[].warning, for the application it applies to; thewarningat the top level is gone.RESTORE_COOLDOWNcarriesdetails.retry_after, also on Rollback. Every answer withdetails.retry_afteralso sends theRetry-Afterheader with the same number of seconds.- Reset Database now needs the
databases:deletescope on the API key (before,databases:write) and, in a workspace, thedatabases:deletepermission (before,databases:manage). A key withdatabases:writeand withoutdatabases:deleteanswers403 API_KEY_SCOPE_DENIED.
New snapshot limits
Manual snapshots are measured over the last 24 hours instead of the calendar day, and the limit grows with your plan.- Account quota: 8 manual snapshots per GB of the plan’s RAM in any 24 hours, at least 2, with no cap: 8 on Starter 1, 16 on Starter 2, 32 to 64 on Pro, 96 to 192 on Business and 256 to 4,096 on Enterprise. A slot frees up 24 hours after it was used, not at midnight. Before, it was 5 to 64 a day.
- Per resource: one snapshot every 3 minutes (before, one every 5 minutes and up to 5 a day). There is no daily limit per resource anymore.
- Per user: one request every 5 seconds.
- Restore: 60 seconds between two restores of the same application; for a database, 60 seconds for the user who asks and 120 seconds per database (before, 30 seconds). Creating an application or a database from a snapshot also waits 60 seconds per user (
429 RESTORE_COOLDOWN). SNAPSHOT_RATE_LIMITEDnow hasdetails.scoperesourceoraccount;accountalso hasresets_at. Theresource_dailyscope no longer exists, and asking again within the 5 seconds answers the generic429 RATE_LIMIT_EXCEEDEDwithretry_after.- Snapshots are no longer limited to 4 GB: the limit is the storage of the resource.
Daily backups by plan
Daily backups now follow the plan: applications from Business and databases from Pro. Starter plans have no daily backup, only manual snapshots. A database that is stopped is not backed up on the daily run.- Retention: every snapshot is kept for 30 days. Of the daily backups, the most recent one of each resource is kept for 30 days and the earlier ones for 7.
- Daily backups do not use the manual snapshot quota.
- List Plans has the new
daily_app_backupsanddaily_database_backupsfeatures.
File manager
The file manager reads and saves files of up to 10 MiB. A larger file answers413 FILE_TOO_LARGE with details.max_bytes; use upload for larger files, and a snapshot download for the whole project.See Back Up and Restore with Snapshots and Plans and limits.