Paginação por cursor
Todos os endpoints de listagem usam paginação por cursor (cursor-based pagination), que é mais eficiente e consistente do que paginação por offset, especialmente em conjuntos de dados que mudam com frequência.Parâmetros de query
Estrutura da resposta
Navegando pelas páginas
1
Primeira página
Faça a requisição sem o parâmetro
cursor:2
Verifique se há mais
Se
meta.has_more for true, use meta.next_cursor na próxima requisição.3
Próximas páginas
Passe o cursor como parâmetro:
4
Última página
Quando
meta.has_more for false, você chegou ao fim da lista.Exemplo: buscar todos os contatos
Notas importantes
- Cursores não são permanentes — não armazene cursores para uso posterior. Eles devem ser usados imediatamente dentro da mesma sessão de paginação.
- Filtros persistem — ao passar um cursor, mantenha os mesmos filtros (
search,tag, etc.) da requisição original. - A ordenação varia por recurso — ver tabela abaixo. Não assuma
created_atem todos. - O total respeita os filtros —
meta.totalconta com os mesmos filtros da listagem, e não muda conforme você pagina: é uma fotografia tirada antes do cursor.
Ordenação por recurso
O cursor é sempre opaco, mas o campo por trás dele muda conforme o recurso. Isso importa quando você guarda o último item visto para retomar depois.Alguns endpoints não paginam:
/pipelines, /custom-fields, /webhooks, /tags, /members,
/whatsapp-instances, /messenger-pages, /instagram-accounts e as notas de contato devolvem a
lista inteira, sempre com has_more: false.
