Skip to main content
Listagens usam paginação por cursor. Em vez de pedir uma página por número, você envia o ID de um objeto recebido anteriormente e continua a partir dele.
Use limit, starting_after e ending_before. A API pública não aceita page para navegar listagens.

Formato da resposta

Toda listagem usa o mesmo envelope:
Uma coleção sem resultados retorna data: [] e has_more: false; isso continua sendo uma resposta 200.

Parâmetros

Envie somente um cursor por request: starting_after ou ending_before.

Percorrer uma lista

1

Busque a primeira página

Comece somente com limit.
Suponha que a resposta contenha cus_z7HgEHQAqUpedPYV e cus_HeZdk47HENVQ9VS2, com has_more: true.
2

Use o último ID para avançar

Envie o ID do último item em starting_after, mantendo o mesmo limite.
3

Pare quando has_more for false

Se a resposta trouxer has_more: false, a navegação chegou ao fim. Não faça outra request usando um array vazio.

Voltar uma página

Use o ID do primeiro item da página atual em ending_before:

Paginar com filtros

Filtros variam por recurso e são documentados em cada endpoint. Preserve os mesmos filtros em todas as páginas; acrescente ou altere apenas o cursor.
Quando um endpoint aceita intervalo, ele usa estes operadores:

Implementação completa

Os dois exemplos percorrem a coleção até has_more ser false.

Erros comuns

Próximos passos

Autenticação

Envie a API key e escolha o contexto correto.

Erros

Trate erros de cursor, autenticação e validação.