Paginação

Toda coleção devolve o mesmo envelope:

{
  "data": [ ... ],
  "meta": { "limit": 50, "has_more": true },
  "links": { "next": "eyJhZnRlciI6W1sic..." }
}

links.next é um cursor. Envie-o de volta no parâmetro cursor — num POST /search, como cursor no corpo — até ele ser null:

params = {"limit": 200}
headers = {"Authorization": f"Bearer {token}"}

while True:
    page = httpx.get("https://api.chatsailer.com/v1/contacts", params=params, headers=headers).json()
    for contact in page["data"]:
        handle(contact)
    if page["links"]["next"] is None:
        break
    params["cursor"] = page["links"]["next"]

As páginas não se movem enquanto os registros mudam

Contatos, organizações e negócios são paginados a partir do último registro que você recebeu, não por posição. Um registro criado ou excluído durante o percurso nunca faz você ver um registro duas vezes nem pular um, e um registro editado no meio do caminho aparece de novo mais adiante com os valores novos. É isso que torna seguro um sync com updated_since — veja Sincronização.

Trate o cursor como opaco

Não parseie, construa nem armazene um cursor além de um percurso. O conteúdo é um detalhe de implementação e muda sem aviso. Um cursor só vale para a consulta que o gerou. Envie-o com os mesmos filtros e o mesmo sort; qualquer outra coisa — um cursor que você montou, um de outro endpoint ou um reaproveitado com outros filtros — devolve 400 invalid_cursor.

Não há contagem total

A resposta diz se existe outra página (meta.has_more), não quantos registros há no total. Contar o conjunto filtrado significaria uma segunda varredura completa a cada página, que fica mais lenta justamente quando o workspace cresce. Se você precisa de uma contagem, pagine e conte o que receber.

Ordenação

Passe sort para ordenar uma coleção, por exemplo sort=-created_at para os mais novos primeiro ou sort=updated_at para percorrer as mudanças em ordem. Prefixe a chave com - para ordem decrescente; registros sem valor ficam por último nos dois sentidos.

Como escolher um limit

limit vale 50 por padrão e aceita até 200. Páginas maiores significam menos idas e voltas; páginas menores, respostas individuais mais rápidas. Para um sync em massa, 200 costuma ser o certo.

Primeiros passos

Trabalhando com a API

As páginas não se movem enquanto os registros mudam

Trate o cursor como opaco

Não há contagem total

Ordenação

Como escolher um limit

​As páginas não se movem enquanto os registros mudam

​Trate o cursor como opaco

​Não há contagem total

​Ordenação

​Como escolher um limit

As páginas não se movem enquanto os registros mudam

Trate o cursor como opaco

Não há contagem total

Ordenação

Como escolher um limit