STAT-API

NBA play_by_plays API

play_by_playsnba.play_by_plays
Every individual event in every NBA game (regular season, play-in, IST, and playoffs — no preseason) — made and missed shots, rebounds, assists, fouls, turnovers, blocks, steals, substitutions, and timeouts, with the game clock at the moment. Period and score context live on game_possessions (FK game_possession_id).
Full field reference (21 columns) → Data DictionaryQuery in GraphQL →
GET/api/v1/nba/play_by_plays
Requires one of: game_id — requests satisfying none of these return 400.
Parameters
game_idquerybigintoptional
Filter to a single game.
player_idquerybigintoptional
Filter to plays involving a specific player.
team_idquerybigintoptional
Filter to plays by a specific team.
event_typequeryintegeroptional
Filter by event type code: 1 made shot, 2 missed shot, 3 free throw, 4 rebound, 5 turnover, 6 foul, 7 violation, 8 substitution, 9 timeout, 10 jump ball, 11 ejection, 12 period start, 13 period end, 18 instant replay (the league codes).
limitqueryintegeroptionaldefault 50
Page size. Defaults to 50; 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/play_by_plays?game_id=1'
Responses
200play_by_plays rows matching the declared filter set, wrapped in { play_by_plays, limit, next_from_id }. next_from_id is the last row's id on a full page — pass it back via ?from_id= to walk the full result; null marks the terminal page.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(21 fields)show schema ▸
FieldTypeReferencesDescription
idkey
bigint—Primary Key
game_id
bigint—
e.g. 2377
game_possession_id
bigint—
e.g. 16457458
play_id
string——
e.g. 0052400111_2
player_id
bigintnullable—
e.g. 49
player2_id
bigintnullable—
e.g. 49
player2_team_id
bigintnullable—
e.g. 21
player3_id
bigintnullable—
e.g. 227
player3_team_id
bigintnullable—
e.g. 21
team_id
bigintnullable—
e.g. 21
end_clock
integernullable——
e.g. — (all-null in sample)
event_seq
integer——
e.g. 100
event_sub_type
integer——
e.g. 0
event_type
integer——
e.g. 8
home_description
string——
e.g.
nba_event_num
integer——
e.g. 2
neutral_description
string——
e.g.
possession_seq
integer——
e.g. 142
start_clock
integer——
e.g. 720
time_actual
timestamptznullable——
e.g. 2025-04-17T01:56:41.900Z
visitor_description
string——
e.g.
GET/api/v1/nba/play_by_plays/{id}
Parameters
idpathbigintrequired
Primary key (id) of the play_by_play 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/play_by_plays/{pk_value}'
Responses
200Single play_by_play row.application/jsonshow example ▸
404Row not found.
Response Schema(21 fields)show schema ▸
FieldTypeReferencesDescription
idkey
bigint—Primary Key
game_id
bigint—
e.g. 2377
game_possession_id
bigint—
e.g. 16457458
play_id
string——
e.g. 0052400111_2
player_id
bigintnullable—
e.g. 49
player2_id
bigintnullable—
e.g. 49
player2_team_id
bigintnullable—
e.g. 21
player3_id
bigintnullable—
e.g. 227
player3_team_id
bigintnullable—
e.g. 21
team_id
bigintnullable—
e.g. 21
end_clock
integernullable——
e.g. — (all-null in sample)
event_seq
integer——
e.g. 100
event_sub_type
integer——
e.g. 0
event_type
integer——
e.g. 8
home_description
string——
e.g.
nba_event_num
integer——
e.g. 2
neutral_description
string——
e.g.
possession_seq
integer——
e.g. 142
start_clock
integer——
e.g. 720
time_actual
timestamptznullable——
e.g. 2025-04-17T01:56:41.900Z
visitor_description
string——
e.g.