Large Tradeics collections (catalogs, RFQs, suppliers, wallet movements) should be fetched page by page. Design clients for pagination before volumes grow.
Conventions to expect
As REST V2 routes expand, list endpoints typically accept:
| Parameter | Role |
|---|---|
limit / page_size |
Page size (cap enforced server-side) |
offset / page |
Offset- or page-based traversal |
cursor / starting_after |
Cursor traversal when offered |
Responses usually include either:
- a
dataarray plus pagination metadata (has_more,next_cursor, totals), or - link headers / next-page tokens documented per route.
Always read the route notes in REST API V2 — do not assume Stripe-identical cursor names until the field is documented.
Client rules
- Cap page size to what the API allows; bigger pages can hit timeouts and rate limits.
- Stop when
has_moreis false / next cursor is empty — never invent offsets. - Stabilize sorts (
created_at,id) when stitching pages for sync jobs. - Persist cursors for incremental syncs; do not restart from page 1 every minute.
- MCP tools that wrap lists should request modest pages so agents stay within token and rate budgets.
Sync pattern
cursor = null
loop:
page = GET /resource?limit=100&cursor=cursor
upsert(page.data)
if not page.has_more: break
cursor = page.next_cursor