Listagem e paginação

As tools *_list usam a mesma paginação da API REST: por número de página.

Argumento	Padrão	Máximo
page	1	—
per_page	20	100

{ "name": "dunning_charges_list", "arguments": { "status": "overdue", "page": 2, "per_page": 50 } }

O resultado traz o envelope de sempre:

{
  "data": [ /* ... */ ],
  "meta": { "total": 142, "page": 2, "per_page": 50, "total_pages": 3 }
}

Campo	Significado
data	Os itens da página pedida
meta.total	Total de itens que atendem aos filtros, não só os devolvidos
meta.page	A página atual
meta.per_page	Itens por página efetivamente aplicado
meta.total_pages	Total de páginas

Quando page > total_pages, data volta vazio — não é erro. Um per_page acima de 100 é VALIDATION_ERROR.

:::note Coleções que não paginam Algumas coleções são pequenas e limitadas por natureza — importações, jobs de exportação, endpoints de webhook, campanhas de negociação. Essas devolvem o conjunto inteiro em data, sem meta, e a tool correspondente não oferece page. Isso é intencional: uma tool que anunciasse page numa rota que o ignora faria o modelo paginar para sempre uma lista que não anda. :::

Ordenação

Argumento	Valores	Padrão
sort_by	Nome de campo em snake_case (due_date, created_at)	varia por recurso
sort_order	asc ou desc	varia por recurso

{ "name": "dunning_charges_list", "arguments": { "sort_by": "due_date", "sort_order": "asc" } }

Duas regras que valem conhecer, porque são diferentes entre si de propósito:

• Um campo que o recurso não ordena cai no padrão. Ordenar por um campo fora da lista do endpoint é um pedido que o servidor não consegue atender, mas também não é motivo para derrubar a chamada inteira.
• Uma direção que não é direção é erro. sort_order: "descending" volta VALIDATION_ERROR, não um desc silencioso — devolver a ordem certa por acidente esconderia o bug até o dia em que o acidente mudasse de lado.

Sem sort_by explícito, não assuma uma ordem estável entre páginas.

Relações (include)

As listagens que têm relações aceitam include, uma lista separada por vírgula das relações a embutir em cada item:

{ "name": "dunning_charges_list", "arguments": { "status": "overdue", "include": "person" } }

Com include: "person", cada cobrança já vem com o devedor — sem uma segunda chamada por item. Quais relações cada tool aceita está no catálogo de tools e na Referência da API.

Filtros

Não há um argumento genérico de filtro: cada tool de listagem tem filtros nomeados, os mesmos da query string do endpoint, em snake_case. Em dunning_charges_list, por exemplo:

Filtro	Exemplo	Significado
status	"pending,overdue"	Um ou mais status, separados por vírgula
due_date_from / due_date_to	"2026-07-01"	Intervalo de vencimento, em YYYY-MM-DD
person_id	"…"	Só as cobranças de um devedor
search	"Maria"	Busca textual

{ "name": "dunning_charges_list",
  "arguments": { "status": "pending,overdue", "due_date_to": "2026-09-30",
                 "sort_by": "due_date", "sort_order": "asc", "per_page": 100 } }

Leituras são estritas: um filtro que a tool não conhece volta VALIDATION_ERROR nomeando a chave, em vez de ser ignorado e devolver a lista inteira com cara de filtrada.

Contrato de dados

O que vale para a API v1 vale aqui, porque é o mesmo código:

• snake_case em tudo, argumentos e respostas.
• Dinheiro é float em BRL, nos dois sentidos — nunca centavos. original_amount: 1500.0 é R$ 1.500,00.
• Datas em YYYY-MM-DD nos filtros e nos campos de data.
• Escritas aceitam idempotency_key — veja Idempotência.