Lists, pagination and dates
Every list endpoint returns one page at a time. This page shows how to read every page, what each page carries besides its items, and how the API reads dates and times.
Read every page
A list response has next_cursor. Pass it back as cursor to get the next page. On the last page, next_cursor is null.
The SDK’s paginate runs that loop for you. It requests each page in turn and yields it:
paginate yields whole pages, not single items, because a page carries more than its items:
- A page of games has
teams, the teams its games reference. - A page of roster entries, injuries, transactions or leaders has
players, the players its items reference. - A page of a game’s plays, drives or roster has
seq, its position in the game’s stream.
Each page’s teams or players covers only that page’s items, so look them up page by page, as above.
Cursors are opaque, so don’t build or edit one. A cursor stays valid indefinitely. The API reads each page when you request it, so an item that changes while you page can move across a page boundary.
Page sizes
Set limit to change the page size. A limit outside the range gets 400 bad_request.
Every page counts as one request against your allowance, so a larger page costs less.
Plays and the stream
Reads of a game’s plays, drives and roster return seq. To follow the game after you page through one of them, resume game:<id> from the first page’s seq. A change that happens while you page arrives on the stream afterwards, so you miss nothing:
Against a test server holding a recorded NFL game, it prints:
The game was over, so both pages had the same seq. During a game, a later page can have a higher one. The stream may then send a change you already read, which is harmless, because every change carries the entity’s full state.
Lists of teams, injuries, transactions and leaders have no seq. Each page is current as of its own read.
Changes page by seq
GET /v1/{league}/games/{id}/changes is the game’s journal, so it pages by after_seq, not by cursor. Pass the last seq you applied. When the last change on the page is at head_seq, you’ve caught up. Live updates has the loop.
paginate doesn’t accept this endpoint, and TypeScript rejects it.
GET /v1/{league}/changes is different. It lists changed entities by time and pages by cursor, so paginate works there. Follow many games shows it.
Dates and times
Timestamps such as scheduled_at and updated_at are RFC 3339 in UTC, like 2026-11-10T01:15:00Z. Dates such as started_on are YYYY-MM-DD.
A day or a range
GET /v1/{league}/games takes either a day or a range of start times, not both:
to is exclusive. A range that ends at a game’s start time leaves that game out.
The time zone changes which day a game is on. The sample NFL game starts at 2026-11-10T01:15:00Z, which is the evening of November 9 in the US. So date=2026-11-09 finds it with tz=America/Los_Angeles. With tz=Europe/London, it’s on November 10.
A time_tbd game has no start time. Its scheduled_at is the start of its day in US Eastern time. With date, the API matches it by that US Eastern day, whatever tz is. With a range, the API matches its scheduled_at.
Rosters
GET /v1/{league}/teams/{id}/roster takes a date and returns the roster as of that day. It defaults to today in US Eastern time.
Season years
A season’s year is the year it starts. The NFL’s 2026 season is 2026, and so are the NBA’s and NHL’s 2026-27 seasons. Pass that year to GET /v1/{league}/seasons/{year}/{season_type}/leaders.