Paginação

GET/api/agenda é a única exceção: ordena por start_at crescente, porque um calendário começa pelo primeiro compromisso da janela, não pelo criado mais recent…

Parâmetro Tipo Padrão Descrição
limit inteiro 1–999 25 Itens por página
cursor texto opaco — Veio de pagination.next_cursor da página anterior
{
  "data": [ { "id": "..." } ],
  "pagination": { "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNi0zMCJ9" }
}
  • next_cursor: null significa última página.
  • O cursor é opaco. Não monte nem interprete o valor — apenas repasse.
  • Não reaproveite um cursor entre listagens diferentes. Não conte com um 400 avisando: ele só acontece quando as duas listagens ordenam por campos diferentes (a Agenda, por start_at, contra o resto). Um cursor de /api/contacts colado em /api/deals é aceito e devolve resultado, porque as duas ordenam pela mesma coluna. O cursor é sempre da listagem que o gerou — trate assim.
  • Ordem padrão: created_at decrescente (mais novos primeiro).

GET/api/agenda é a única exceção: ordena por start_at crescente, porque um calendário começa pelo primeiro compromisso da janela, não pelo criado mais recentemente.

GET/api/products também tem regra própria: limit vai de 1 a 100 (padrão 25), a ordem padrão é por nome, crescente, e você pode trocá-la com ?sort= (ex.: name, sku, price, stock, created) e ?dir=asc|desc. Valor fora da lista devolve 400 dizendo quais são aceitos.

Nem toda listagem pagina. Os catálogos pequenos — funis (seção 12), origens (seção 9.2), motivos de perda (seção 9.3), campos personalizados (seção 28), planos de comissão (seção 20), categorias de produto e o catálogo de eventos de webhook (seção 21) — devolvem tudo de uma vez, sempre com next_cursor: null, e recusam ?limit=/?cursor= com 400 ("parâmetro não reconhecido"). A paginação por cursor desta seção vale pras listagens principais (contatos, empresas, negócios, tarefas, conversas, tags, webhooks…).

Filtro por janela de data

GET/api/contacts, /api/companies, /api/deals e /api/tasks aceitam ?created_after=, ?created_before=, ?updated_after=, ?updated_before= — cada um em ISO 8601 completo, com fuso: 2026-01-01T00:00:00Z. ⛔ Só a data (2026-01-01) é 400 — sem hora e sem fuso não há como saber a que instante você se refere. Combine os dois de um par pra fatiar a migração em janelas (útil pra base grande, pra não puxar tudo de uma vez); mandar o "depois" depois do "antes" no mesmo par devolve 400 nomeando o par.