Paginação
Os formatos de paginação usados pelos endpoints de listagem da API, incluindo o cursor para exportação completa.
A API não usa um único formato de paginação em todos os endpoints — o formato depende do endpoint. Consulte a tabela abaixo antes de integrar.
Toda listagem paginada tem ordem estável: além da coluna principal de ordenação, os registros são desempatados por id, então dois registros com o mesmo valor na coluna principal nunca trocam de posição entre uma página e outra.
| Endpoint | Formato |
|---|---|
| GET /api/v1/contacts | Envelope pagination por página (padrão) ou por cursor com order_by=created_at |
| GET /api/v1/messages | Envelope pagination |
| GET /api/v1/campaigns/{id}/recipients | Campos planos total/page/limit |
| GET /api/v1/campaigns | Sem paginação — retorna todos os registros |
| GET /api/v1/lists | Sem paginação — retorna todos os registros |
| GET /api/v1/custom-fields | Sem paginação — retorna todos os registros |
Envelope `pagination`
Usado por GET /api/v1/contacts e GET /api/v1/messages. Os dados ficam em data; os metadados de paginação, em um objeto pagination à parte.
{
"success": true,
"data": [],
"pagination": {
"page": 1,
"limit": 50,
"total": 132,
"total_pages": 3
}
}Cursor
Usado por GET /api/v1/contacts?order_by=created_at para exportar a base inteira sem repetir nem pular contatos, mesmo que eles recebam mensagens durante a leitura. A ordem é created_at crescente com desempate por id.
Faça a primeira chamada sem cursor. Enquanto pagination.next_cursor vier preenchido, envie esse valor no parâmetro cursor da chamada seguinte, mantendo os mesmos filtros; next_cursor: null indica a última página. total é a contagem com os mesmos filtros. O parâmetro page não é aceito nesse modo, e um cursor adulterado devolve 400 INVALID_PARAMETER.
O cursor não expira: se a exportação receber 429 pelo rate limit, aguarde e repita a chamada com o mesmo cursor.
{
"success": true,
"data": [
{
"id": "3f2b8c1e-9a4d-4e6f-8b21-0c5d7e9fa123",
"name": "João Silva",
"created_at": "2026-09-09T16:42:22.950942+00:00"
}
],
"pagination": {
"limit": 1,
"total": 13815,
"next_cursor": "eyJjIjoiMjAyNi0wOS0wOVQxNjo0MjoyMi45NTA5NDIrMDA6MDAiLCJpIjoiM2YyYjhjMWUtOWE0ZC00ZTZmLThiMjEtMGM1ZDdlOWZhMTIzIn0"
}
}Formato plano
Usado por GET /api/v1/campaigns/{id}/recipients. Os metadados de paginação ficam no nível raiz da resposta, junto dos dados — não há objeto pagination separado.
{
"success": true,
"data": [],
"total": 48,
"page": 1,
"limit": 50
}Sem paginação
GET /api/v1/campaigns, GET /api/v1/lists e GET /api/v1/custom-fields retornam todos os registros da empresa em data, sem parâmetros nem metadados de paginação — o volume desses recursos é tipicamente baixo o suficiente para não exigir paginação.
{
"success": true,
"data": []
}