> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Snapshot

> Perform a snapshot of your database. It has a rate limit of 1 request every 5 seconds.

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

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/account/security).
</ParamField>

### Parameters

<ParamField path="database_id" type="string" placeholder="Database ID" required>
  The ID of the database.
</ParamField>

### 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](/en/api-reference/endpoint/databases/snapshots/list) on its own, typically within \~2 minutes. This is expected behavior for large databases.

<Warning>
  Do not use this `POST` endpoint as a polling mechanism. To check whether a `SNAPSHOT_PROCESSING` snapshot has completed, use the [List Snapshots](/en/api-reference/endpoint/databases/snapshots/list) (`GET`) endpoint — **not** another `POST`. Re-posting after the snapshot has finished starts a brand-new snapshot from scratch.
</Warning>

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](/en/api-reference/endpoint/databases/snapshots/list) (`GET`). Do **not** re-`POST`. |
| `status === "error"` with any other `code`                | Actual failure.               | Handle the error (see below).                                                                                                           |

### Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful.. `success` if successful, `error` if not.
</ResponseField>

<ResponseField name="response" type="object">
  The contents of the response. Present only when `status` is `success`.

  <Expandable title="Toggle object">
    <ResponseField name="url" type="string">
      The URL to download the snapshot of your application.
    </ResponseField>

    <ResponseField name="key" type="string">
      The key to download the snapshot of your application.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="SNAPSHOT_PROCESSING" type="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.
</ResponseField>

### Errors

A snapshot request can be rejected with `429 Too Many Requests`. Use the `code` field to tell the two cases apart:

<ResponseField name="KEEP_CALM" type="429">
  Short-term cooldown — you hit the per-user (1 request / 5s) or per-database (1 request / 180s) limit. Back off and retry shortly.
</ResponseField>

<ResponseField name="DAILY_SNAPSHOTS_LIMIT_REACHED" type="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.
</ResponseField>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "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"
    }
  }
  ```

  ```json 202 SNAPSHOT_PROCESSING theme={null}
  {
    "status": "error",
    "code": "SNAPSHOT_PROCESSING"
  }
  ```

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

  ```json 429 DAILY_SNAPSHOTS_LIMIT_REACHED theme={null}
  {
    "status": "error",
    "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
    "message": "You are being rate limited for daily snapshots. 8r/24h"
  }
  ```
</ResponseExample>