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

# Polling delta (aggiornamenti)

> Non ricaricare tutto il board — prendi solo le quote cambiate.

Ricaricare tutto il board a ogni richiesta è uno spreco. Al suo posto apri una **sessione**: uno snapshot stabilisce la tua base, poi arrivano i delta calcolati rispetto a essa.

1. **`/api/snapshot`** restituisce lo stato attuale e ti rilascia un `token`. È qui che dichiari il tuo perimetro.
2. **`/api/updated?since=<token>`** restituisce solo le **righe modificate** da quel token, più un nuovo token per la chiamata seguente.

`/api/updated` non restituisce mai uno snapshot: senza `since` risponde `400`. La separazione è voluta — un endpoint chiamato *updated* che restituisse tutto il book sarebbe spiazzante, e costoso.

```bash theme={null}
# 1) aprire la sessione — il token viene rilasciato qui
curl https://api.apinn.io/api/snapshot -H "X-API-Key: LA_TUA_CHIAVE"
# → { "snapshot": true, "token": "2026-07-24T15:36:48", "count": 33572, "odds": [ ... ] }

# 2) poi interrogare i delta, rimandando l'ultimo token ricevuto
curl "https://api.apinn.io/api/updated?since=2026-07-24T15:36:48" -H "X-API-Key: LA_TUA_CHIAVE"
# → { "snapshot": false, "token": "2026-07-24T15:37:12", "window_seconds": 25, "count": 168, "odds": [ ... ] }
```

Il campo `window_seconds` indica l'intervallo coperto dal tuo delta — comodo per regolare la cadenza.

## Definire il perimetro della sessione

La chiamata allo snapshot è anche il punto in cui dici **di che cosa parla la tua sessione**. Aggiungi `sport_id`, `league_id`, `event_id`, `market` o `period` (sono accettate liste separate da virgole): lo snapshot si limita a quel perimetro, e il token ricevuto **porta con sé quel perimetro**.

Da quel momento invii solo il token. Il server sa su quale base calcolare il delta, e il tuo perimetro non può cambiare a metà sessione perché hai dimenticato un parametro.

```bash theme={null}
# 1) lo snapshot fissa il perimetro
curl "https://api.apinn.io/api/snapshot?sport_id=29&market=moneyline&period=0" -H "X-API-Key: LA_TUA_CHIAVE"
# → { "snapshot": true, "token": "v1.eyJ0cyI6...", "scope": { "sports": [29], "markets": ["moneyline"], "periods": [0] }, "count": 510, ... }

# 2) il token da solo basta — non serve ripetere i filtri
curl "https://api.apinn.io/api/updated?since=v1.eyJ0cyI6..." -H "X-API-Key: LA_TUA_CHIAVE"
# → { "snapshot": false, "scope": { ... }, "count": 3, "odds": [ ... ] }
```

Ogni risposta riporta lo `scope`, così sai sempre che cosa significa il tuo token. Per cambiare perimetro, apri una nuova sessione con un nuovo snapshot.

## Quanto costa

Una chiamata costa **1 + il numero di righe restituite**. La frequenza è quasi gratuita; ciò che paghi è il volume. Due conseguenze vanno messe in conto.

Il perimetro è la leva principale sulla tua fattura. Misurato sul book in diretta, un perimetro moneyline / tempi regolamentari rappresenta circa il 5 % dei movimenti — quindi all'incirca il 5 % del costo di seguire tutto. Anche il tuo snapshot è fatturato allo stesso modo, ed è l'altra ragione per delimitarlo: uno snapshot dell'intero book supera le 20 000 righe.

Interrogare più spesso non ti dà dati più freschi gratis. Un prezzo che si muove cinque volte in trenta secondi compare **una sola volta** in un delta di 30 secondi, e fino a cinque volte con intervalli di 5 secondi, perché il cursore segue l'ultima variazione reale di ogni mercato. Una cadenza più rapida compra granularità, non freschezza.

<Note>
  Conserva l'ultimo `token` ricevuto e rimandalo a ogni chiamata. I token sono opachi: trattali come un cursore, non come un orario che puoi calcolare.
</Note>

<Tip>
  Se vuoi un perimetro in continuo invece che a intervalli, il [flusso WebSocket](/it/concepts/websocket) costa molto meno: la connessione vale **1 richiesta**, una sola volta, e accetta gli stessi filtri sotto forma di sottoscrizione.
</Tip>