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

> Realizar um snapshot da sua aplicação. Possui limite de taxa de 1 requisição a cada 5 segundos.

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

### Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação. Você pode encontrá-lo na URL do painel da sua aplicação.
</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/apps/snapshots/list), normalmente em até \~2 minutos. Esse é o comportamento esperado para aplicações 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/apps/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/apps/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 bem-sucedida, `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 aplicação (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={null}
  {
      "status": "success",
      "response": {
          "url": "https://snapshots.squarecloud.app/applications/23457145698959364/a23d130fcc9ddaf2d288ae9599a4292c32.zip?AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D",
          "key": "AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%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>