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

ParâmetroTipoPadrãoDescrição
limitinteger25Número de itens por página. Mínimo: 1, máximo: 100
cursorstring—Token da próxima página (obtido de meta.next_cursor)

​
Estrutura da resposta

{
  "data": [...],
  "meta": {
    "total": 350,
    "has_more": true,
    "next_cursor": "eyJpZCI6IjY2NGYxYTJiM2M0ZDVlNmY3ODkwMTIzNCIsImNhIjoiMjAyNi0wMS0xNVQxMDozMDowMC4wMDBaIn0",
    "request_id": "req_01jx8kz3m4n5p6q7r8s9t0u1v"
  }
}
CampoTipoDescrição
meta.totalintegerTotal de registros na organização (sem filtros)
meta.has_morebooleanSe existem mais páginas
meta.next_cursorstring | nullToken para a próxima página. null quando has_more é false
1

Primeira página

Faça a requisição sem o parâmetro cursor:
GET /v1/contacts?limit=50
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:
GET /v1/contacts?limit=50&cursor=eyJpZCI6IjY2NGYxYTJiM2M0ZDVlNmY3ODkwMTIzNCIsImNhIjoiMjAyNi0wMS0xNVQxMDozMDowMC4wMDBaIn0
4

Última página

Quando meta.has_more for false, você chegou ao fim da lista.

​
Exemplo: buscar todos os contatos

async function getAllContacts() {
  const contacts = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({ limit: '100' });
    if (cursor) params.set('cursor', cursor);

    const response = await fetch(
      `https://api.socialsell.ai/v1/contacts?${params}`,
      { headers: { 'Authorization': 'Bearer sk_live_...' } }
    );
    const { data, meta } = await response.json();

    contacts.push(...data);
    cursor = meta.has_more ? meta.next_cursor : null;
  } while (cursor);

  return contacts;
}

​
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.
  • Ordem não muda — a ordenação padrão é por created_at decrescente (mais recentes primeiro).
  • O total é aproximado — meta.total reflete a contagem sem filtros aplicados.