> ## 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.

# List database snapshots

> List a database's snapshots, newest first, with GET /v2/databases/{database_id}/snapshots: size, date, download URL and the IDs to restore each one.

<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/en/account/security).
</ParamField>

Requires an API key with the `snapshots:read` [scope](/en/api-reference/authentication#scopes).

Lists every snapshot stored for a database, most recent first, with size and last-modified date for each. Use it to build a restore picker in a dashboard, or to poll after a [Create Snapshot](/en/api-reference/endpoint/databases/snapshots/create) call returned `202 SNAPSHOT_PROCESSING` and confirm the file has landed.

Each item carries a signed download `url`, valid for 30 days, and a `version_id` to pass as `versionId` when restoring. Responses are cached for 30 minutes per user and database, so a snapshot that just finished generating may take a short while to show up here. To restore one of these snapshots, see [Restore Snapshot](/en/api-reference/endpoint/databases/snapshots/restore).

## Parameters

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

## Response

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

<ResponseField name="response" type="array">
  The contents of the response.

  <Expandable title="Toggle object">
    <ResponseField name="name" type="string">
      The snapshot's name: the database ID suffixed with `_<type>` and, on newer snapshots, `_<origin>`. Pass it unchanged as `snapshotId` when restoring.
    </ResponseField>

    <ResponseField name="size" type="number">
      Size of the backup in bytes.
    </ResponseField>

    <ResponseField name="modified" type="string">
      Date of the last modification of the backup.
    </ResponseField>

    <ResponseField name="key" type="string">
      The signed query string of the download URL.
    </ResponseField>

    <ResponseField name="version_id" type="string">
      The snapshot's version. Pass it as `versionId` when restoring.
    </ResponseField>

    <ResponseField name="url" type="string">
      A signed URL that downloads the snapshot, valid for 30 days.
    </ResponseField>

    <ResponseField name="runtime" type="string | null">
      Runtime the snapshot was taken from: the application's language (`javascript`, `python`, `rust`...) or the database engine (`mongo`, `mysql`, `postgres`, `redis`). `null` on snapshots taken before this field existed.
    </ResponseField>

    <ResponseField name="origin" type="string | null">
      How the snapshot was created: `manual` (requested through the API, dashboard or CLI) or `automatic` (the daily scheduled snapshot). `null` on older snapshots.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={"system"}
  {
    "status":"success",
    "response":[
      {
        "name":"a14b8d5e1cb7405a851eb4c075506121_mongo_manual",
        "size":10644463,
        "modified":"2025-08-13T13:29:11.263Z",
        "key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=VZ03MSxcNw3%2FtPezXv0IhTs0jq4%3D&versionId=45ec0b49-9af6-445e-a55c-abd7ec5278b2",
        "version_id":"45ec0b49-9af6-445e-a55c-abd7ec5278b2",
        "url":"https://snapshots.squarecloud.app/databases/<account_id>/<name>.zip?<signed-query-string>",
        "runtime":"mongo",
        "origin":"manual"
      },
      {
        "name":"a14b8d5e1cb7405a851eb4c075506121_mongo_automatic",
        "size":2742383,
        "modified":"2025-08-13T00:01:47.010Z",
        "key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=7zw5apjyaOd1xPZl3gRgp8Y4yEs%3D&versionId=f65e1378-8717-45c5-8aec-bb233eedb5ce",
        "version_id":"f65e1378-8717-45c5-8aec-bb233eedb5ce",
        "url":"https://snapshots.squarecloud.app/databases/<account_id>/<name>.zip?<signed-query-string>",
        "runtime":"mongo",
        "origin":"automatic"
      }
    ]
  }
  ```
</ResponseExample>

<Note>Download a snapshot from its `url`. The link stays valid for 30 days.</Note>

## Common errors

| Code | HTTP | Meaning |
| - | - | - |
| `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. |

## Related

* CLI: [`squarecloud db snapshot list`](/en/cli-reference/snapshots#squarecloud-db-snapshot-list)
* SDKs: [`api.databases.snapshots.list()`](/en/sdks/js/databases) (JavaScript), [`client.databases.snapshots.list()`](/en/sdks/py/databases) (Python), [`c.Databases.Snapshots.List()`](/en/sdks/go/databases) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.