National Basketball Association
NBA API. Every shot with its type, its value and its spot on the court.
Scores, play-by-play, box scores and game rosters for every NBA game, in the same schema as Statpad's football and soccer leagues. Read it over REST, or stream every change over one WebSocket.
- Alias
- nba
- Status
- Live
- REST
- from $19 a month
- WebSocket
- from $49 a month
Sample game
Lakers 124 at Hawks 114. November 9, 2026.
These are untrimmed responses from the real API for one NBA game, free to download without a key. The game was replayed through Statpad's ingest into a fresh database, so the ids and every updated_at are from that run.
A finished game with 467 plays: every shot, rebound, turnover, foul, free throw, timeout and substitution, with the players involved and the score after each play.
The files are the exact bodies the API returned after the final, untrimmed.
Its play-by-play has 467 entries:
field_goal174defensive_rebound67substitution56free_throw46turnover36foul34offensive_rebound32timeout10
{
"away_score": 124,
"basketball": {
"court_x": 9,
"court_y": 21,
"free_throw": null,
"free_throws": null,
"is_made": true,
"play_type": "field_goal",
"points_attempted": 3,
"shot_type": "jump_shot"
},
"clock_seconds": 53,
"description": "Matisse Thybulle makes 25-foot three point jumper (Sandro Mamukelashvili assists)",
"football": null,
"game_id": "01a1e5f6-6d6c-730b-995a-c3fd2a14a9a2",
"group_id": null,
"hockey": null,
"home_score": 114,
"id": "01a1e5f6-6d6c-7ab7-8d68-cf1a333be165",
"is_official": true,
"is_scoring": true,
"participants": [
{
"player_id": "01a1e5f6-6d6c-733a-a20b-942e2e05aca4",
"role": "assist",
"team_id": "01a1e5f6-6d6c-7317-aa8c-05b49e4d6cc0"
},
{
"player_id": "01a1e5f6-6d6c-732c-9a75-827f62749464",
"role": "shooter",
"team_id": "01a1e5f6-6d6c-7317-aa8c-05b49e4d6cc0"
}
],
"period": 4,
"period_half": null,
"points": 3,
"sequence": 40667000000686,
"soccer": null,
"team_id": "01a1e5f6-6d6c-7317-aa8c-05b49e4d6cc0",
"type": "field_goal",
"updated_at": "2026-11-16T20:04:54.762239Z",
"version": 1,
"wall_clock": "2026-11-10T02:21:03Z"
}The last made three of the game. A shot carries shot_type, points_attempted, is_made and court_x and court_y, and participants names the shooter and the assist.
{
"game_id": "01a1e5f6-6d6c-730b-995a-c3fd2a14a9a2",
"player_id": "01a1e5f6-6d6c-7330-88c4-2601c03382e7",
"stats": {
"basketball": {
"blocks": 2,
"points": 32,
"steals": 5,
"assists": 10,
"minutes": 39,
"rebounds": 8,
"turnovers": 6,
"plus_minus": 4,
"personal_fouls": 2,
"field_goals_att": 22,
"free_throws_att": 7,
"field_goals_made": 11,
"free_throws_made": 7,
"three_points_att": 11,
"three_points_made": 3,
"defensive_rebounds": 8,
"offensive_rebounds": 0
}
},
"team_id": "01a1e5f6-6d6c-7317-aa8c-05b49e4d6cc0",
"version": 1
}Luka Doncic's line in the box score: one basketball category with minutes, shooting, rebounds, assists and plus_minus.
Every file from this game
A whole NFL game you can replay change by change is on Sample responses.
Endpoints
REST at https://api.statpad.dev and one WebSocket at wss://stream.statpad.dev/v1/stream. Every league uses the same paths and JSON, so changing nba to another alias keeps your parser working.
| Request or stream | What it returns |
|---|---|
| GET /v1/nba/games?date=2026-11-10 | A day's games with status, start time and score. Pass from and to instead for a range of up to 31 days. |
| GET /v1/nba/games/{id} | One game with its teams, venue and live state |
| GET /v1/nba/games/{id}/plays | Every play or match event, in game order |
| GET /v1/nba/games/{id}/boxscore | A stat line for each player |
| GET /v1/nba/games/{id}/roster | The players in the game, with team and jersey |
| GET /v1/nba/games/{id}/changes?after_seq=0 | Every change after a seq: the same journal the stream sends |
| GET /v1/nba/teams | The league's teams |
| game:<id> | WebSocket stream for one game: the game, its live state, plays, stats and roster, in seq order |
| league:nba | WebSocket stream for what the league's games share: teams, players and venues, plus injuries |
A client that reconnects to the stream with the last seq it saw gets exactly the changes it missed. The API reference has every parameter and schema.
What every NBA game has
The fields below are what the sample game's responses contain. Coverage by league has the list of what isn't filled yet for every league.
- Shots with shot_type, points_attempted, is_made and court_x and court_y
- Free throws numbered within the trip, as free_throw 1 of free_throws 2
- Each player's role on a play: shooter, assist, rebounder, stealer, blocker, fouler, player_in and player_out
- Game rosters with starters, positions and jerseys
- The field-by-field table on /docs/coverage covers football and soccer and doesn't describe basketball yet, so this page lists what the sample game's responses contain. The not-filled-yet list below applies to every league.
- NBA games run in quarters. GET /v1/leagues says so with period_kind quarter and regulation_periods 4.
Box score stat codes in this game
| Category | Codes |
|---|---|
| basketball | blocks, points, steals, assists, minutes, rebounds, turnovers, plus_minus, personal_fouls, field_goals_att, free_throws_att, field_goals_made, free_throws_made, three_points_att, three_points_made, defensive_rebounds, offensive_rebounds |
A player only has the categories and codes that apply to them, so treat every code as optional.
Not filled yet
These endpoints and fields are part of the API, but nothing fills them for NBA today. Code written against them keeps working when the data arrives.
| Data | Where | What you get today |
|---|---|---|
| Team totals | teams in the box score | An empty list. Add up the player lines for team totals. |
| Score by period | period_scores on the game and the box score | An empty list. Plays carry the score after each play. |
| Team rosters | GET /teams/{id}/roster | An empty list. A game's roster lists the players in that game. |
| Depth charts | GET /teams/{id}/depth-chart | 404 |
| Injuries | GET /{league}/injuries | An empty list |
| Injury practice status and notes | practice_status and comment on an injury | null |
| Transactions | GET /{league}/transactions?since= | An empty list |
| Season stats and leaders | GET /players/{id}/stats, GET /seasons/{year}/{type}/leaders | Empty lists |
| Player details | birth_date, height_in, weight_lb, college and draft on players | null |
History, and staying right
Statpad started collecting each league in November 2026 and doesn't backfill earlier games or seasons. Once collected, a game's plays, box score and roster stay readable over REST for good, and its change journal for at least 7 days after it ends.
A play or stat line can change after it first appears, during the game and shortly after it. The newer version arrives as an upsert with a higher version, on the same stream and in the same seq order as everything else. Key what you store by id and keep the highest version, and your app shows the current data with no special handling.
Pricing
Every plan includes all 10 leagues and every REST endpoint. Plans differ in volume, streaming and keys, and the limits are hard caps with no overage.
Compare every limitDeveloper
$19 a month
- 25,000 requests a month
- 1 request a second, burst of 10
- REST only, no WebSocket
Pro
$49 a month
- 150,000 requests a month
- 10 requests a second, burst of 30
- WebSocket: 5 connections, 20 subscriptions
Business
$299 a month
- 2,000,000 requests a month
- 25 requests a second, burst of 100
- WebSocket: 10 connections, 150 subscriptions