> ## 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 (atualizações)

> Não recarregue todo o board — obtenha só as odds que mudaram.

Recarregar todo o board em cada pedido é um desperdício. Em vez disso, abre uma **sessão**: um snapshot estabelece a sua base, e depois vêm os deltas calculados em relação a ela.

1. **`/api/snapshot`** devolve o estado atual e entrega-lhe um `token`. É aqui que declara o seu âmbito.
2. **`/api/updated?since=<token>`** devolve apenas as **linhas alteradas** desde esse token, mais um novo token para a chamada seguinte.

`/api/updated` nunca devolve um snapshot: sem `since` responde `400`. A separação é deliberada — um endpoint chamado *updated* que devolvesse todo o book seria desconcertante, e caro.

```bash theme={null}
# 1) abrir a sessão — é aqui que o token é emitido
curl https://api.apinn.io/api/snapshot -H "X-API-Key: A_SUA_CHAVE"
# → { "snapshot": true, "token": "2026-07-24T15:36:48", "count": 33572, "odds": [ ... ] }

# 2) depois consultar os deltas, devolvendo o último token recebido
curl "https://api.apinn.io/api/updated?since=2026-07-24T15:36:48" -H "X-API-Key: A_SUA_CHAVE"
# → { "snapshot": false, "token": "2026-07-24T15:37:12", "window_seconds": 25, "count": 168, "odds": [ ... ] }
```

O campo `window_seconds` indica o período coberto pelo seu delta — útil para acertar a sua cadência.

## Definir o âmbito da sua sessão

A chamada ao snapshot é também onde diz **do que trata a sua sessão**. Acrescente `sport_id`, `league_id`, `event_id`, `market` ou `period` (aceitam-se listas separadas por vírgulas): o snapshot fica limitado a esse âmbito, e o token recebido **transporta esse âmbito consigo**.

A partir daí envia apenas o token. O servidor sabe sobre que base calcular o delta, e o seu âmbito não pode desviar-se a meio da sessão por ter esquecido um parâmetro.

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

# 2) o token só por si basta — não é preciso repetir os filtros
curl "https://api.apinn.io/api/updated?since=v1.eyJ0cyI6..." -H "X-API-Key: A_SUA_CHAVE"
# → { "snapshot": false, "scope": { ... }, "count": 3, "odds": [ ... ] }
```

Cada resposta reflete o `scope`, para que saiba sempre o que significa o seu token. Para mudar de âmbito, abra uma nova sessão com um novo snapshot.

## Quanto custa

Uma chamada custa **1 + o número de linhas devolvidas**. A frequência é quase gratuita; o que se paga é o volume. Duas consequências merecem ser antecipadas.

O âmbito é a principal alavanca sobre a sua fatura. Medido no book em direto, um âmbito moneyline / tempo regulamentar representa cerca de 5 % dos movimentos — ou seja, cerca de 5 % do custo de seguir tudo. O seu snapshot é faturado da mesma forma, e essa é a outra razão para o delimitar: um snapshot do book inteiro ultrapassa as 20 000 linhas.

Consultar mais vezes não lhe dá dados mais frescos de graça. Um preço que se move cinco vezes em trinta segundos aparece **uma só vez** num delta de 30 segundos, e até cinco vezes com intervalos de 5 segundos, porque o cursor segue a última alteração real de cada mercado. Uma cadência mais rápida compra granularidade, não frescura.

<Note>
  Guarde o último `token` recebido e devolva-o em cada chamada. Os tokens são opacos: trate-os como um cursor, não como uma marca temporal que possa calcular.
</Note>

<Tip>
  Se quiser um âmbito em contínuo em vez de a intervalos, o [fluxo WebSocket](/pt/concepts/websocket) é bastante mais barato: a ligação custa **1 pedido**, uma única vez, e aceita os mesmos filtros sob a forma de subscrição.
</Tip>