NBA seasons API
seasons
nba.seasonsEach NBA league year, running from October through June — the 82-game regular season, the play-in tournament, and the four-round playoffs that end with the NBA Finals.
GET/api/v1/nba/seasonsList seasons for NBA
Parameters
limitqueryintegeroptionaldefault 25Page size. Defaults to 25; max 5000.
from_idquerybigintoptionalReturn rows with id strictly greater than this value; page using the previous response's `next_from_id`. Omit on the first page.
Restores the documented defaults (trial keys only accept the unchanged defaults).
Request
curl -sS --compressed \
-H 'Authorization: Bearer YOUR_API_KEY' \
'https://api.stat-api.com/api/v1/nba/seasons?limit=3'Responses
200seasons rows matching the declared filter set, wrapped in { seasons, limit, next_from_id, has_more }. has_more is true when another row follows this page. To walk every row, start with ?from_id=0 and pass each next_from_id back as from_id until it is null; the filters stay. A first page without from_id comes in the default order and gives next_from_id null.application/jsonshow example ▸
400No declared filter set was satisfied — response body matches MissingRequiredFiltersError; pick one combo from the accepted-sets hint and resend.
application/jsonResponse Schema(6 fields)show schema ▸
| Field | Type | References | Description |
|---|---|---|---|
idkey | bigint | — | Primary Key |
end_date | timestamptznullable | — | — e.g. 2017-06-12T04:00:00.000Z |
post_season_start_date | timestamptznullable | — | — e.g. 2017-04-15T04:00:00.000Z |
regular_season_start_date | timestamptznullable | — | — e.g. 2016-10-25T04:00:00.000Z |
start_date | timestamptz | — | — e.g. 2016-10-25T04:00:00.000Z |
start_year | integer | — | — e.g. 2016 |
GET/api/v1/nba/seasons/{id}Get a single season by id
Parameters
idpathbigintrequiredPrimary key (id) of the season row.
Restores the documented defaults (trial keys only accept the unchanged defaults).
Request
curl -sS --compressed \
-H 'Authorization: Bearer YOUR_API_KEY' \
'https://api.stat-api.com/api/v1/nba/seasons/{pk_value}'Responses
200Single season row.application/jsonshow example ▸
404Row not found.
Response Schema(6 fields)show schema ▸
| Field | Type | References | Description |
|---|---|---|---|
idkey | bigint | — | Primary Key |
end_date | timestamptznullable | — | — e.g. 2017-06-12T04:00:00.000Z |
post_season_start_date | timestamptznullable | — | — e.g. 2017-04-15T04:00:00.000Z |
regular_season_start_date | timestamptznullable | — | — e.g. 2016-10-25T04:00:00.000Z |
start_date | timestamptz | — | — e.g. 2016-10-25T04:00:00.000Z |
start_year | integer | — | — e.g. 2016 |
GET/api/v1/nba/weeksList modeled NBA season weeks and matchup summaries (Free navigation endpoint, plus free_game_id for SIM)beta
Parameters
seasonqueryunknownoptionalNBA season year (defaults to 2026).
weekqueryunknownoptionalOptional week number filter.
season_typequeryunknownoptionalModeled season phase (`regular_season`, `in_season_tournament`, `play_in`, `postseason`; preseason is excluded per Rule 3.4).
Restores the documented defaults (trial keys only accept the unchanged defaults).
Request
curl -sS --compressed \
-H 'Authorization: Bearer YOUR_API_KEY' \
'https://api.stat-api.com/api/v1/nba/weeks?season=2026'Responses
200List modeled NBA season weeks and matchup summaries (Free navigation endpoint, plus free_game_id for SIM)application/jsonshow example ▸
Response Schema(5 fields)show schema ▸
25 total fields (1 nested object/array groups)
| Field | Type | References | Description |
|---|---|---|---|
season | integer | — | Requested NBA season year (default `2026`). |
available_seasons | integer[] | — | Available NBA seasons in the database (`[2026, 2025, ...]`). |
free_game_id | integer | — | Canonical free 2026 game ID (`6029936`, `DET @ BOS`) unlocked in full for all tiers. |
weeks | integer[] | — | Sorted list of modeled week numbers available in `season`. |
games | NBAMatchupSummary[] | — | Matchup summaries across modeled NBA games in `season` (regular season, NBA Cup, play-in, and playoffs; never preseason). |
↳game_id games.game_id | integer | — | Unique NBA game identifier (`6029936` = `DET @ BOS`). |
↳season games.season | integer | — | NBA season year. |
↳week games.week | integer | — | NBA season week number. |
↳season_type games.season_type | string | — | Modeled NBA season phase (`regular_season`, `in_season_tournament`, `play_in`, `postseason`). |
↳kickoff games.kickoff | stringnullable | — | Scheduled UTC tipoff timestamp (ISO-8601). |
↳day games.day | integernullable | — | Game date integer in `YYYYMMDD` format. |
↳home_team_id games.home_team_id | integer | — | Canonical home team ID. |
↳home_abbr games.home_abbr | string | — | Home team abbreviation (e.g., `BOS`). |
↳away_team_id games.away_team_id | integer | — | Canonical away team ID. |
↳away_abbr games.away_abbr | string | — | Away team abbreviation (e.g., `DET`). |
↳spread_home games.spread_home | number | — | Pre-tip Vegas home spread in points (negative = home favored). |
↳game_total games.game_total | number | — | Pre-tip Vegas over/under game total points. |
↳home_team_total games.home_team_total | number | — | Implied home team total points (`(game_total - spread_home) / 2`). |
↳away_team_total games.away_team_total | number | — | Implied away team total points (`(game_total + spread_home) / 2`). |
↳moneyline_home games.moneyline_home | integernullable | — | Pre-tip American moneyline for the home team. |
↳moneyline_away games.moneyline_away | integernullable | — | Pre-tip American moneyline for the away team. |
↳is_final games.is_final | boolean | — | True if the real NBA game has completed. |
↳real_home_pts games.real_home_pts | integernullable | — | Actual final home points scored (`null` before game completion). |
↳real_away_pts games.real_away_pts | integernullable | — | Actual final away points scored (`null` before game completion). |
↳is_free games.is_free | boolean | — | True when unlocked for free full-depth simulation (`game_id == 6029936`). |