> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://statpad.dev/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://statpad.dev/docs/_mcp/server.

# Lists, pagination and dates

> How Statpad list endpoints paginate, their page sizes, the sidecar arrays, the first-page seq rule, and how the API reads dates, time zones, ranges and season years.

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`**

```ts title="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`.

| Endpoint                              | Default | Maximum |
| ------------------------------------- | ------- | ------- |
| `GET /v1/{league}/games/{id}/plays`   | 500     | 1000    |
| `GET /v1/{league}/games/{id}/changes` | 500     | 1000    |
| `GET /v1/{league}/changes`            | 1000    | 5000    |
| Every other list                      | 100     | 500     |

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`**

```ts title="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:

```text
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](/docs/streaming#without-the-stream) 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](/docs/many-games#poll-the-changes-window) 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:

| Parameters                 | What it matches                                                                                      |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| `date`, with optional `tz` | Games that start on that calendar day in the IANA time zone `tz`. The default is `America/New_York`. |
| `from` and `to`            | Games 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`.