Create a database snapshot

POST

databases

{database_id}

snapshots

Create a database snapshot

curl --request POST \
  --url https://api.squarecloud.app/v2/databases/{database_id}/snapshots \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.squarecloud.app/v2/databases/{database_id}/snapshots"

headers = {"Authorization": "<authorization>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/databases/{database_id}/snapshots', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/databases/{database_id}/snapshots",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/databases/{database_id}/snapshots"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/databases/{database_id}/snapshots")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "status": "error",
  "code": "SNAPSHOT_PROCESSING"
}

{
  "status": "error",
  "code": "KEEP_CALM",
  "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
}

{
  "status": "error",
  "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
  "message": "You are being rate limited for daily snapshots. 8r/24h"
}

Each account can perform up to (RAM / 256) * 2 snapshots every 24 hours.

string

required

The API key for your account. You can find this in your account settings.

Requires an API key with the snapshots:write scope. Captures a point-in-time backup of the database’s data and uploads it to Square Cloud’s snapshot storage, returning a signed download URL valid for 30 days. Use it before a risky migration, a manual Restore Snapshot, or on a schedule for disaster recovery. Once created, snapshots also show up in List Snapshots.

Parameters

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:

Response	Meaning	What 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 `code`	Actual failure.	Handle the error (see below).

Response

string

Indicates whether the call was successful: success if it was, error if not.

object

The contents of the response. Present only when status is success.

Show Toggle object

string

The URL to download the snapshot of your application.

string

The key to download the snapshot of your application.

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:

429

Short-term cooldown: you hit the per-user (1 request / 5s) or per-database (1 request / 180s) limit. Back off and retry shortly.

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"
  }
}

{
  "status": "error",
  "code": "SNAPSHOT_PROCESSING"
}

{
  "status": "error",
  "code": "KEEP_CALM",
  "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
}

{
  "status": "error",
  "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
  "message": "You are being rate limited for daily snapshots. 8r/24h"
}

CLI: squarecloud db snapshot create
SDKs: api.databases.snapshots.create() (JavaScript), client.databases.snapshots.create() (Python), c.Databases.Snapshots.Create() (Go)

Create a database snapshot

curl --request POST \
  --url https://api.squarecloud.app/v2/databases/{database_id}/snapshots \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.squarecloud.app/v2/databases/{database_id}/snapshots"

headers = {"Authorization": "<authorization>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/databases/{database_id}/snapshots', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/databases/{database_id}/snapshots",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/databases/{database_id}/snapshots"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/databases/{database_id}/snapshots")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "status": "error",
  "code": "SNAPSHOT_PROCESSING"
}

{
  "status": "error",
  "code": "KEEP_CALM",
  "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
}

{
  "status": "error",
  "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
  "message": "You are being rate limited for daily snapshots. 8r/24h"
}

Get started

Account

Applications

Databases

Workspaces

AI

Create a database snapshot

Parameters

Soft deadline behavior

Response

Errors

​Parameters

​Soft deadline behavior

​Response

​Errors

​Related

Parameters

Soft deadline behavior

Response

Errors

Related