Skip to main content
POST
/
v2
/
databases
/
{database_id}
/
snapshots
Create Snapshot
curl --request POST \
  --url https://api.squarecloud.app/v2/databases/{database_id}/snapshots \
  --header 'Authorization: <authorization>'
{
  "status":"success",
  "response":{
    "url":"https://snapshots.squarecloud.app/databases/384443501775028242/a14b8d5e1cb7405a851eb4c075506121.zip?AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D",
    "key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D"
  }
}
Each account can perform up to (RAM / 256) * 2 snapshots every 24 hours.
​
Authorization
string
required
The API key for your account. You can find this in your account settings.

​
Path

​
database_id
string
required
The ID of the database.

​
Soft deadline behavior

This route follows a soft deadline model — it no longer always responds synchronously.
  • If the snapshot finishes within ~90 seconds, the route responds with 200 success and a signed download URL (valid for 30 days), exactly as before.
  • If the snapshot takes longer than ~90 seconds to generate, the route responds immediately with 202 and the code SNAPSHOT_PROCESSING. This is not a failure. The snapshot keeps generating in the background and will appear in the snapshot listing on its own, typically within ~2 minutes. This is expected behavior for large databases.
Do not use this POST endpoint as a polling mechanism. To check whether a SNAPSHOT_PROCESSING snapshot has completed, use the List Snapshots (GET) endpoint — not another POST. Re-posting after the snapshot has finished starts a brand-new snapshot from scratch.
The client should branch on the response as follows:
ResponseMeaningWhat to do
status === "success"Snapshot is ready.Use the url to download it.
status === "error" and code === "SNAPSHOT_PROCESSING"Snapshot is still generating.Wait ~2 minutes, then confirm via List Snapshots (GET). Do not re-POST.
status === "error" with any other codeActual failure.Handle the error (see below).

​
Response

​
status
string
Indicates whether the call was successful.. success if successful, error if not.
​
response
object
The contents of the response. Present only when status is success.
​
SNAPSHOT_PROCESSING
202
Returned when the snapshot exceeds the ~90 second soft deadline. The snapshot is still being generated in the background and will appear in the snapshot listing on its own, typically within ~2 minutes. Not an error — wait and confirm via the GET listing endpoint.

​
Errors

A snapshot request can be rejected with 429 Too Many Requests. Use the code field to tell the two cases apart:
​
KEEP_CALM
429
Short-term cooldown — you hit the per-user (1 request / 5s) or per-database (1 request / 180s) limit. Back off and retry shortly.
​
DAILY_SNAPSHOTS_LIMIT_REACHED
429
Daily quota reached — the account used up its plan’s daily snapshot allowance ((RAM / 256) × 2 per 24h). The quota frees up as the rolling 24-hour window advances; for a higher daily allowance, upgrade the plan.
{
  "status":"success",
  "response":{
    "url":"https://snapshots.squarecloud.app/databases/384443501775028242/a14b8d5e1cb7405a851eb4c075506121.zip?AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D",
    "key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D"
  }
}