Skip to main content

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

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_at em todos.
  • O total respeita os filtros — meta.total conta 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.