Skip to navigation

Lists, pagination and dates

Page through lists with cursors, and pass dates and times the way the API reads them.

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:

schedule.mts
import { Statpad, paginate } from "@statpad/sdk";
const statpad = new Statpad({ apiKey: process.env.STATPAD_API_KEY! });
for await (const page of paginate(statpad.games.listGames, { path: { league: "nfl" }, query: { date: "2026-11-09" } })) {
const teams = new Map(page.teams.map((team) => [team.id, team]));
for (const game of page.data) {
console.log(`${teams.get(game.away_team_id)?.alias} at ${teams.get(game.home_team_id)?.alias}, ${game.scheduled_at}`);
}
}

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.

EndpointDefaultMaximum
GET /v1/{league}/games/{id}/plays5001000
GET /v1/{league}/games/{id}/changes5001000
GET /v1/{league}/changes10005000
Every other list100500

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:

plays.mts
import { Statpad, paginate } from "@statpad/sdk";
const statpad = new Statpad({ apiKey: process.env.STATPAD_API_KEY! });
const path = { league: "nfl", game_id: process.argv[2] };
let resumeFrom: number | undefined;
let count = 0;
for await (const page of paginate(statpad.playByPlay.listPlays, { path, query: { limit: 100 } })) {
resumeFrom ??= page.seq;
count += page.data.length;
console.log(`page: ${page.data.length} plays, seq ${page.seq}, next_cursor ${page.next_cursor ? "set" : "null"}`);
}
console.log(`${count} plays. Resume game:${path.game_id} from seq ${resumeFrom}.`);

Against a test server holding a recorded NFL game, it prints:

page: 100 plays, seq 514, next_cursor set
page: 87 plays, seq 514, next_cursor null
187 plays. Resume game:01a1f1b2-e35c-77cc-8601-b28866a7e64e from seq 514.

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:

ParametersWhat it matches
date, with optional tzGames that start on that calendar day in the IANA time zone tz. The default is America/New_York.
from and toGames that start at or after from and before to. They can be at most 31 days apart.

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.