Skip to main content
List routes return one page at a time. To pull a long history, follow the cursor until it runs out. The mechanics are the same across every paginated route.

​
How a page is bounded

Two things cap a single response:
  • limit sets the maximum rows returned. The default and ceiling vary by route (for example, trades default 100 / max 1000; order routes default 1000 / max 10000). Check the data-type page or OpenAPI for the exact numbers.
  • The time window (start/end) bounds the range. A narrow window plus a sensible limit keeps each page fast.

​
Follow the cursor

Every paginated response carries meta.next_cursor. To get the next page, send it back as the cursor query parameter: 
# first page
curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?limit=1000" -H "X-API-Key: $OXARCHIVE_API_KEY"
# next page: pass meta.next_cursor as cursor
curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?limit=1000&cursor=1780581219809_333265093496905" -H "X-API-Key: $OXARCHIVE_API_KEY"
When meta.next_cursor is absent or null, you have reached the end of the window.

​
Treat the cursor as opaque

Cursor encodings differ by route: some are composite strings such as timestamp_tradeId, others are integers. Do not parse, construct, or compare cursors. Store the exact value you received and pass it back unchanged. That keeps your iteration correct even if the encoding changes.

​
Resumable backfills

For a long backfill, persist the last next_cursor (and the window you are walking) with your job state. A run that stores its cursor can pause and resume without duplicating rows or re-pulling the whole range. Keep meta.request_id per page in your logs so a failed page is traceable.

​
Pair it with bounded windows

Pagination and bounded windows work together: split a long history into windows you can retry independently, then paginate within each. That gives you a job you can checkpoint, resume, and explain, instead of one unbounded loop. See Parameters for the window formats and Build a reliable client for retry behavior.
Last modified on June 8, 2026