offset, which return a next_cursor, the default and maximum limit of every list, and how to know you have reached the end. You need it for anything that reads more than one page.
Which endpoint pages how
Ranked and searched lists page by offset. Lists that can be long and change underneath you page by cursor. Everything else takes alimit and returns one page.
Offset endpoints
Cursor endpoints
GET /v1/stream also takes a cursor, but it is an event id used to resume the stream, not a page; see Live stream.
Single-page endpoints
These take alimit and return at most that many items, best first.
A
limit outside its range is rejected with 400 invalid_parameter.
Cursors
A cursor endpoint returnsnext_cursor whenever the page was full, that is, it returned exactly limit items. Pass it back as cursor, unchanged, with the same other parameters. The last page is the first one that comes back without next_cursor; when the total is an exact multiple of limit, that last page is empty.
Cursors are opaque and their format may change. A cursor the server cannot read is rejected:
GET /v1/markets?q=bitcoin&limit=2:
executed_at and id, so a fill recorded while you page is not skipped and not repeated.
1367 trades for the Python example and 1456 markets for the JavaScript one.
Offsets
Passoffset as the number of items to skip. For GET /v1/search, the response says where the next page starts:
next_offset is offset + limit and is absent on the last page. Search never goes past 300 results: offset=250&limit=50 returned 50 results and no next_offset.
For GET /v1/events, /relations and /v1/cross-venue there is no marker: add limit to offset until a page comes back with fewer than limit items. GET /v1/events?category=World&limit=6&offset=6 returned 4 items, so that was the last page.
Consistency across pages
Graph-derived lists read from the latest finished graph run, named ingraph_run. Runs finish hourly. If a new run finishes while you page, later pages come from the new run: compare graph_run across pages when that matters, and restart from the first page if it changed. Offsets also shift when the ranking underneath changes, for example when a market’s 24-hour volume moves it up a list; cursor endpoints do not have this problem.