Pagination (discovery endpoints)

Cursor pagination applies to the JSON discovery and reference endpoints only: /v1/teams, /v1/players, /v1/games. They return a page envelope:

{
  "data": [ ... ],
  "next_cursor": "eyJ..."
}

• limit — rows per page. Defaults to 1000, max 10000.
• cursor — pass the previous response’s next_cursor back verbatim to fetch the next page. next_cursor: null means you have everything.

Cursors are opaque keyset tokens. Don’t parse, construct, or store them long-term — they encode a position in a specific sorted result set and are only meaningful for the same query with the same filters.

curl -s "https://api.betflux.ai/v1/games?league=NBA&date_from=2026-04-01&date_to=2026-04-07&cursor=eyJ..." \
  -H "Authorization: Bearer $BETFLUX_API_KEY"

(/v1/leagues uses the same envelope but always fits one page, so its next_cursor is always null.)

Dataset files don’t paginate

Dataset payloads (GET /v1/games/{game_id}/{dataset}) are one Parquet file per game — there is no cursor, no page size, and no server-side row slicing. You get the whole artifact (or a byte range of it via HTTP Range — see Response formats).

Multi-game pulls are a client-side loop: page through /v1/games for the ids in your window, then fetch each game’s file. The SDK’s iter() and the CLI’s range flags do exactly this for you.

SDK auto-pagination

The Python SDK paginates the discovery endpoints transparently — bf.games(), bf.teams(), and bf.players() follow cursors and return complete lists; bf.closing_lines.iter(...) uses the paginated /v1/games under the hood to find which files to fetch:

for row in bf.closing_lines.iter(league="NBA", date_from="2026-01-01", date_to="2026-04-01"):
    ...