STAT-API

NBA seasons API

seasonsnba.seasons
Each 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/seasons
Parameters
limitqueryintegeroptionaldefault 25
Page size. Defaults to 25; max 5000.
from_idquerybigintoptional
Return 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/json
Response Schema(6 fields)show schema ▸
FieldTypeReferencesDescription
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}
Parameters
idpathbigintrequired
Primary 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 ▸
FieldTypeReferencesDescription
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/weeksbeta
Parameters
seasonqueryunknownoptional
NBA season year (defaults to 2026).
weekqueryunknownoptional
Optional week number filter.
season_typequeryunknownoptional
Modeled 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)
FieldTypeReferencesDescription
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`).