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

# Crea Snapshot

> Esegui uno snapshot della tua applicazione. Ha un limite di frequenza di 1 richiesta ogni 5 secondi.

<Warning>Ogni account può eseguire fino a (RAM / 256) \* 2 snapshot ogni 24 ore.</Warning>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La chiave API del tuo account. Puoi trovarla nelle [impostazioni del tuo account](https://squarecloud.app/it/account/security).
</ParamField>

### Parametri

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  L'ID dell'applicazione. Puoi trovarlo nell'URL della dashboard della tua applicazione.
</ParamField>

### Comportamento con soft deadline

Questa route segue un modello a **soft deadline** — non risponde più sempre in modo sincrono.

* Se lo snapshot termina entro **\~90 secondi**, la route risponde con `200 success` e un URL di download firmato (valido per 30 giorni), esattamente come prima.
* Se lo snapshot impiega più di **\~90 secondi** per essere generato, la route risponde **immediatamente** con `202` e il codice `SNAPSHOT_PROCESSING`. **Questo non è un errore.** Lo snapshot continua a essere generato in background e comparirà da solo nell'[elenco degli snapshot](/it/api-reference/endpoint/apps/snapshots/list), tipicamente entro \~2 minuti. Questo è il comportamento atteso per le applicazioni di grandi dimensioni.

<Warning>
  Non usare questo endpoint `POST` come meccanismo di polling. Per verificare se uno snapshot `SNAPSHOT_PROCESSING` è stato completato, usa l'endpoint [List Snapshots](/it/api-reference/endpoint/apps/snapshots/list) (`GET`) — **non** un altro `POST`. Rieseguire il `POST` dopo che lo snapshot è terminato avvia un nuovo snapshot da zero.
</Warning>

Il client dovrebbe ramificare in base alla risposta come segue:

| Risposta                                                | Significato                          | Cosa fare                                                                                                                                        |
| ------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status === "success"`                                  | Lo snapshot è pronto.                | Usa l'`url` per scaricarlo.                                                                                                                      |
| `status === "error"` e `code === "SNAPSHOT_PROCESSING"` | Lo snapshot è ancora in generazione. | Attendi \~2 minuti, poi conferma tramite [List Snapshots](/it/api-reference/endpoint/apps/snapshots/list) (`GET`). **Non** rieseguire il `POST`. |
| `status === "error"` con qualsiasi altro `code`         | Fallimento effettivo.                | Gestisci l'errore (vedi sotto).                                                                                                                  |

### Risposta

<ResponseField name="status" type="string">
  Indica se la chiamata è andata a buon fine. `success` in caso di successo, `error` in caso contrario.
</ResponseField>

<ResponseField name="response" type="object">
  Il contenuto della risposta. Presente solo quando `status` è `success`.

  <Expandable title="Mostra oggetto">
    <ResponseField name="url" type="string">
      L'URL per scaricare lo snapshot della tua applicazione.
    </ResponseField>

    <ResponseField name="key" type="string">
      La chiave per scaricare lo snapshot della tua applicazione.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="SNAPSHOT_PROCESSING" type="202">
  Restituito quando lo snapshot supera la soft deadline di \~90 secondi. Lo snapshot è ancora in generazione in background e comparirà da solo nell'elenco degli snapshot, tipicamente entro \~2 minuti. Non è un errore — attendi e conferma tramite l'endpoint di elenco `GET`.
</ResponseField>

### Errori

Una richiesta di snapshot può essere rifiutata con `429 Too Many Requests`. Usa il campo `code` per distinguere i due casi:

<ResponseField name="KEEP_CALM" type="429">
  Cooldown a breve termine — hai raggiunto il limite per utente (1 richiesta / 5s) o per applicazione (1 richiesta / 180s). Attendi e riprova a breve.
</ResponseField>

<ResponseField name="DAILY_SNAPSHOTS_LIMIT_REACHED" type="429">
  Quota giornaliera raggiunta — l'account ha esaurito il numero di snapshot giornalieri consentiti dal suo piano ((RAM / 256) × 2 ogni 24h). La quota si libera man mano che la finestra mobile di 24 ore avanza; per un limite giornaliero più alto, effettua l'upgrade del piano.
</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>