Paginação

Os endpoints de lista da API retornam dados paginados. Na plataforma, coexistem historicamente dois esquemas de paginação; o esquema específico é indicado no endpoint na referência interativa.

Esquema 1 — deslocamento e X-Total-Count

Paginação clássica por deslocamento. A requisição aceita os parâmetros de query limit (tamanho da página) e offset (quantos registros pular):

curl -H "Authorization: Bearer mbp_SEU_TOKEN" "https://seu-dominio/api/bots/BOT_ID/subscribers?limit=50&offset=100"

O número total de registros é retornado no cabeçalho de resposta X-Total-Count. Com ele, calcula-se o número de páginas: navegue aumentando offset em limit, enquanto offset for menor que o valor de X-Total-Count. O corpo da resposta é um array de elementos da página atual.

Esquema 2 — cursor before e has_more

Paginação por cursor para feeds ordenados por tempo (por exemplo, mensagens de diálogo). A requisição aceita limit e o cursor opcional before — identificador ou marcador do último elemento já recebido:

curl -H "Authorization: Bearer mbp_SEU_TOKEN" "https://seu-dominio/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

A resposta contém uma página de elementos e o flag has_more. Enquanto has_more for true, repita a requisição passando em before o cursor do último elemento recebido. Quando has_more for false — é a última página.

Qual esquema escolher

Você não escolhe o esquema — ele é definido pelo endpoint. Listas de referência normalmente usam deslocamento e X-Total-Count; feeds temporais usam cursor before e has_more. Sempre consulte a página do endpoint na referência.

Próximos passos