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

# Criar snapshot do banco de dados

> Faça backup dos dados de um banco com POST /v2/databases/{database_id}/snapshots. Retorna uma URL de download válida por 30 dias, ou 202 enquanto é gerado.

<Warning>Cada conta pode executar até (RAM / 256) \* 2 snapshots a cada 24 horas.</Warning>

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `snapshots:write`.

Captura um backup pontual dos dados do banco de dados e o envia para o armazenamento de snapshots da Square Cloud, retornando uma URL de download assinada válida por 30 dias. Use isso antes de uma migração arriscada, de uma [Restauração de Snapshot](/pt-br/api-reference/endpoint/databases/snapshots/restore) manual, ou em uma agenda para recuperação de desastres. Depois de criados, os snapshots também aparecem em [Listar Snapshots](/pt-br/api-reference/endpoint/databases/snapshots/list).

## Parâmetros

<ParamField path="database_id" type="string" placeholder="ID do banco de dados" required>
  O ID do banco de dados.
</ParamField>

## Comportamento de prazo flexível (soft deadline)

Esta rota segue um modelo de **prazo flexível (soft deadline)**: ela não responde mais sempre de forma síncrona.

* Se o snapshot terminar em até **\~90 segundos**, a rota responde com `200 success` e uma URL de download assinada (válida por 30 dias), exatamente como antes.
* Se o snapshot levar mais de **\~90 segundos** para ser gerado, a rota responde **imediatamente** com `202` e o código `SNAPSHOT_PROCESSING`. **Isso não é uma falha.** O snapshot continua sendo gerado em segundo plano e aparecerá sozinho na [listagem de snapshots](/pt-br/api-reference/endpoint/databases/snapshots/list), normalmente em até \~2 minutos. Esse é o comportamento esperado para bancos de dados grandes.

<Warning>
  Não use este endpoint `POST` como mecanismo de polling. Para verificar se um snapshot em `SNAPSHOT_PROCESSING` foi concluído, use o endpoint [Listar Snapshots](/pt-br/api-reference/endpoint/databases/snapshots/list) (`GET`), e **não** outro `POST`. Repetir o `POST` depois que o snapshot terminar inicia um snapshot completamente novo do zero.
</Warning>

O cliente deve tratar a resposta da seguinte forma:

| Resposta | Significado | O que fazer |
| - | - | - |
| `status === "success"` | O snapshot está pronto. | Use a `url` para baixá-lo. |
| `status === "error"` e `code === "SNAPSHOT_PROCESSING"` | O snapshot ainda está sendo gerado. | Aguarde \~2 minutos e confirme via [Listar Snapshots](/pt-br/api-reference/endpoint/databases/snapshots/list) (`GET`). **Não** repita o `POST`. |
| `status === "error"` com qualquer outro `code` | Falha real. | Trate o erro (veja abaixo). |

## Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `error` se não.
</ResponseField>

<ResponseField name="response" type="object">
  O conteúdo da resposta. Presente apenas quando `status` é `success`.

  <Expandable title="Alternar objeto">
    <ResponseField name="url" type="string">
      A URL para baixar o snapshot da sua aplicação.
    </ResponseField>

    <ResponseField name="key" type="string">
      A chave para baixar o snapshot da sua aplicação.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="SNAPSHOT_PROCESSING" type="202">
  Retornado quando o snapshot ultrapassa o prazo flexível de \~90 segundos. O snapshot continua sendo gerado em segundo plano e aparecerá sozinho na listagem de snapshots, normalmente em até \~2 minutos. Não é um erro: aguarde e confirme via o endpoint de listagem `GET`.
</ResponseField>

## Erros

Uma requisição de snapshot pode ser rejeitada com `429 Too Many Requests`. Use o campo `code` para distinguir os dois casos:

<ResponseField name="KEEP_CALM" type="429">
  Cooldown de curto prazo: você atingiu o limite por usuário (1 requisição / 5s) ou por banco de dados (1 requisição / 180s). Aguarde um instante e tente novamente.
</ResponseField>

<ResponseField name="DAILY_SNAPSHOTS_LIMIT_REACHED" type="429">
  Cota diária atingida: a conta esgotou o limite diário de snapshots do plano ((RAM / 256) × 2 por 24h). A cota é renovada conforme a janela de 24 horas avança; para um limite diário maior, faça upgrade do plano.
</ResponseField>

<ResponseExample>
  ```json 200 Success theme={"system"}
  {
    "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={"system"}
  {
    "status": "error",
    "code": "SNAPSHOT_PROCESSING"
  }
  ```

  ```json 429 KEEP_CALM theme={"system"}
  {
    "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={"system"}
  {
    "status": "error",
    "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
    "message": "You are being rate limited for daily snapshots. 8r/24h"
  }
  ```
</ResponseExample>

## Relacionados

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


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