Paginazione
Ottieni un elenco lungo a pagine senza saltare record: dimensione della pagina, offset e cursore before.
In questa pagina
L'API restituisce gli elenchi lunghi, come clienti o messaggi, in parti chiamate pagine. Caricare le pagine successive si chiama paginazione: il programma non deve ricevere l'intera cronologia in una sola richiesta.
Per proseguire ci sono due metodi: saltare un numero di record già letti (offset) oppure passare un puntatore all'ultimo punto letto (cursore). Il metodo di ogni endpoint è indicato nel riferimento API.
Schema 1: offset e X-Total-Count
limit indica la dimensione della pagina e offset quanti record saltare. Per esempio, limit=50&offset=100 richiede fino a 50 record dopo i primi 100. I parametri si aggiungono all'indirizzo dopo ?:
curl -H "Authorization: Bearer <TOKEN_PERSONALE>" \
"https://tuo-dominio/api/bots/BOT_ID/users?limit=50&offset=100"
Il numero totale di record arriva nell'intestazione X-Total-Count. Dopo ogni risposta aumenta offset del numero di record effettivamente ricevuti, finché resta inferiore a X-Total-Count. Il corpo della risposta è l'array degli elementi della pagina corrente.
Limite massimo dell'offset
Non puoi continuare all'infinito solo perché offset è inferiore a X-Total-Count. Un offset maggiore di 100.000 viene rifiutato con 400 da qualsiasi endpoint che accetti l'offset. La risposta indica di restringere il filtro o usare la paginazione a cursore.
Un offset grande costringe il database a elaborare i record saltati per ottenere la pagina successiva. Per elenchi grandi usa filtri, cursori o esportazioni.
Se l'elenco supera 100.000 record, l'offset non può raggiungerne la fine. Puoi:
- restringere la selezione con i filtri dell'endpoint, per esempio periodo, canale o stato;
- usare un cursore se l'endpoint lo supporta (schema 2; gli elenchi dei pagamenti e dei record delle raccolte supportano entrambi);
- esportare i dati della sezione se ti serve l'intero insieme, invece di percorrere tutte le pagine.
Ogni endpoint ha il proprio limite per la pagina
Non esiste un massimo unico per limit: a seconda dell'elenco può essere 200, 500 o 1000. Verifica il valore nella pagina dell'endpoint nel riferimento.
Anche il comportamento se chiedi un limit eccessivo varia, ed è più importante del numero stesso:
- alcuni endpoint rifiutano la richiesta con
400, per esempio «limit must be at most 500, got 5000»; - altri usano silenziosamente il valore predefinito, spesso 100, e restituiscono meno elementi del richiesto.
Perciò non dare mai per scontato di aver ricevuto il numero di elementi richiesto. Controlla la lunghezza dell'array e aumenta offset esattamente di quel numero. Altrimenti, se chiedi 5000 elementi e ne ricevi 100, salteresti il 98% dei dati senza alcun errore.
Per lo stesso motivo, non usare una pagina vuota come unico segnale di fine: considera insieme X-Total-Count e il numero di elementi ricevuti.
Schema 2: cursore before e has_more
La paginazione a cursore si usa per i feed ordinati nel tempo, per esempio i messaggi di una conversazione. La richiesta accetta limit e il cursore opzionale before, cioè l'ID o il marcatore dell'ultimo elemento già ricevuto:
curl -H "Authorization: Bearer <TOKEN_PERSONALE>" \
"https://tuo-dominio/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"
La risposta contiene una pagina di elementi e il flag has_more. Finché vale true, ripeti la richiesta passando in before il cursore dell'ultimo elemento ricevuto. Quando diventa false, hai ricevuto l'ultima pagina.
Quale schema scegliere
Non sei tu a scegliere lo schema: lo stabilisce l'endpoint. Gli elenchi di riferimento di solito usano offset e X-Total-Count, mentre i feed ordinati nel tempo usano before e has_more. Controlla sempre la pagina dell'endpoint nel riferimento.
Passo successivo
- Avvio rapido API — prime richieste.
- Errori — codici di stato.
- Limiti e dimensioni — limitazioni delle richieste.