> 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.

# Basketball

> How Statpad describes NBA, men's college basketball and WNBA games, including the basketball live state, play types, shot details, box score stat codes and the differences between the leagues.

The NBA (`nba`), NCAA Division I men's basketball (`ncaab`) and the WNBA (`wnba`) share one data model. A game in any of them fills the same endpoints and the same `basketball` blocks, so the same code reads all three. The leagues differ in period length and in a few fields, listed under [League differences](#league-differences).

The examples come from two recorded games: the [Lakers at the Hawks](https://statpad.dev/samples/nba-lakers-at-hawks/plays.json) in the NBA on November 9, 2026, and [Wagner at UConn](https://statpad.dev/samples/ncaab-wagner-at-uconn/plays.json) in NCAAB the same night.

## Live state

`live_state` on `GET /v1/{league}/games/{id}` carries the situation in its `basketball` block. The other sports' blocks are `null`.

| Field                                                  | What it is                                                                         |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `period`                                               | The quarter in the NBA and WNBA, the half in NCAAB. A later period is an overtime. |
| `clock_seconds`                                        | Seconds left in the period, rounded up, so `0` means the period is over.           |
| `clock_running`                                        | Always `null`. The basketball feed doesn't say whether the clock is running.       |
| `possession_team_id`                                   | The team with the ball, or `null` when the feed doesn't say, as after the final.   |
| `basketball.home_timeouts`, `basketball.away_timeouts` | Timeouts each team has left.                                                       |
| `basketball.home_fouls`, `basketball.away_fouls`       | Each team's fouls in the current period.                                           |

The `basketball` block is there only while the game is in progress. After the final it's `null`, and `period` and `clock_seconds` keep the end of the game, such as period 4 at `0`.

Each count is `null` when the feed doesn't report it. The feed doesn't track timeouts and fouls for most college games, so in NCAAB the four counts are often `null` all game.

## Periods and overtime

| League | `period_kind` | `regulation_periods` | Regulation              | Overtime       |
| ------ | ------------- | -------------------- | ----------------------- | -------------- |
| NBA    | `quarter`     | 4                    | Four 12-minute quarters | 5 minutes each |
| WNBA   | `quarter`     | 4                    | Four 10-minute quarters | 5 minutes each |
| NCAAB  | `half`        | 2                    | Two 20-minute halves    | 5 minutes each |

Every period after regulation is another overtime, so an NBA game's period 6 is its second overtime and an NCAAB game's period 3 is its first. [Build a scoreboard](/docs/scoreboard#the-period) turns a period number into a label such as `2nd half` or `2OT`, and [the clock section](/docs/scoreboard#the-clock) formats `clock_seconds`.

## Plays

`GET /v1/{league}/games/{id}/plays` lists every event. It returns a page of events, 500 by default and up to 1,000 with `limit`, with a `next_cursor` for the rest. [Lists, pagination and dates](/docs/pagination) shows how to page. A play's `type` and its `basketball.play_type` are the same value, one of these:

| `play_type`                                                  | The event                                                                                |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `field_goal`                                                 | A two- or three-point shot, made or missed                                               |
| `free_throw`                                                 | A free throw, made or missed                                                             |
| `offensive_rebound`, `defensive_rebound`                     | A rebound                                                                                |
| `rebound`                                                    | A rebound the feed doesn't call offensive or defensive, such as a dead-ball team rebound |
| `turnover`, `steal`, `block`                                 | A turnover, or a steal or block filed as its own event                                   |
| `foul`, `technical_foul`, `flagrant_foul`                    | A foul                                                                                   |
| `violation`                                                  | A violation such as goaltending, a kicked ball or a lane violation                       |
| `timeout`, `substitution`, `jump_ball`, `review`, `ejection` | What the name says                                                                       |
| `period_start`, `period_end`, `game_end`                     | The start or end of a period, and the end of the game                                    |
| `other`                                                      | Anything else                                                                            |

The `basketball` block on each play:

| Field                       | What it is                                                                                                                                                                                                                    |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `points_attempted`          | What a shot was worth: `1` for a free throw, `2` or `3` for a field goal, and `0` for any other event.                                                                                                                        |
| `is_made`                   | Whether the shot went in.                                                                                                                                                                                                     |
| `shot_type`                 | A field goal's style: `jump_shot`, `layup`, `dunk`, `hook_shot` or `tip_shot`. `null` on other events, or when the feed doesn't say.                                                                                          |
| `free_throw`, `free_throws` | A free throw's place in its trip to the line, so the second of two is `2` of `2`. `null` when the feed doesn't say, as on a technical free throw.                                                                             |
| `court_x`, `court_y`        | Where a field goal was taken from, in feet. `court_x` runs across the court from 0 to 50. `court_y` runs along it from the basket the team attacks, so it's negative behind the basket. `null` when the feed has no position. |

`points` and `is_scoring` say what the play scored, and `home_score` and `away_score` are the score after it. `team_id` is the team credited with the event, which for a shot is the shooting team, even when another team's player blocked it.

Each play's `participants` lists the players in it with a `role`: `shooter`, `assist`, `blocker`, `rebounder`, `stealer`, `fouler`, `player_in` and `player_out` on a substitution, or `player` for any other part, such as the players in a jump ball or the player who turned it over. A team rebound has no participants. Join each participant's `player_id` to `players[].id` in the game roster response, not to the box score, because a player in a play can have no stat line. `description` is the feed's play text.

This is a made three in the NBA sample, from `plays.json`, unedited:

```json
{
  "away_score": 0,
  "basketball": {
    "court_x": 27,
    "court_y": 25,
    "free_throw": null,
    "free_throws": null,
    "is_made": true,
    "play_type": "field_goal",
    "points_attempted": 3,
    "shot_type": "jump_shot"
  },
  "clock_seconds": 690,
  "description": "Onyeka Okongwu makes 24-foot running jump shot (Kingston Flemings assists)",
  "football": null,
  "game_id": "01a1e5f6-6d6c-730b-995a-c3fd2a14a9a2",
  "group_id": null,
  "hockey": null,
  "home_score": 3,
  "id": "01a1e5f6-6d6c-7395-bdbf-0e01da948e73",
  "is_official": true,
  "is_scoring": true,
  "participants": [
    {
      "player_id": "01a1e5f6-6d6c-736a-beb4-29cabc88d024",
      "role": "assist",
      "team_id": "01a1e5f6-6d6c-7312-8095-49b16b3b06a5"
    },
    {
      "player_id": "01a1e5f6-6d6c-735a-80b8-5687fdb6155d",
      "role": "shooter",
      "team_id": "01a1e5f6-6d6c-7312-8095-49b16b3b06a5"
    }
  ],
  "period": 1,
  "period_half": null,
  "points": 3,
  "sequence": 10030000000009,
  "soccer": null,
  "team_id": "01a1e5f6-6d6c-7312-8095-49b16b3b06a5",
  "type": "field_goal",
  "updated_at": "2026-11-16T20:04:54.762239Z",
  "version": 1,
  "wall_clock": "2026-11-10T00:10:57Z"
}
```

The Hawks went up 3 to 0 with 11:30 left in the 1st quarter. The assist is a second participant on the same play.

## Play groups

Basketball has no drives or possessions in the data. Every play's `group_id` is `null`, and `GET /v1/{league}/games/{id}/play-groups` returns an empty list.

## Box score

`GET /v1/{league}/games/{id}/boxscore` has one line per player who played. Each line holds one category, `basketball`:

| Code                                                   | What it is                                                                 |
| ------------------------------------------------------ | -------------------------------------------------------------------------- |
| `minutes`                                              | Minutes played, in whole minutes                                           |
| `points`                                               | Points                                                                     |
| `field_goals_made`, `field_goals_att`                  | Field goals made and attempted, threes included                            |
| `three_points_made`, `three_points_att`                | Three-pointers made and attempted                                          |
| `free_throws_made`, `free_throws_att`                  | Free throws made and attempted                                             |
| `rebounds`, `offensive_rebounds`, `defensive_rebounds` | Rebounds, in total and by end                                              |
| `assists`, `turnovers`, `steals`, `blocks`             | What the names say                                                         |
| `personal_fouls`                                       | Personal fouls                                                             |
| `plus_minus`                                           | The point difference while the player was on the court. NBA and WNBA only. |

These are the stats of a Lakers player in the NBA sample, unedited:

```json
{
  "basketball": {
    "blocks": 0,
    "points": 12,
    "steals": 2,
    "assists": 2,
    "minutes": 28,
    "rebounds": 2,
    "turnovers": 0,
    "plus_minus": 5,
    "personal_fouls": 1,
    "field_goals_att": 10,
    "free_throws_att": 0,
    "field_goals_made": 5,
    "free_throws_made": 0,
    "three_points_att": 5,
    "three_points_made": 2,
    "defensive_rebounds": 2,
    "offensive_rebounds": 0
  }
}
```

Treat every code as optional, and ignore codes you don't use. [Build a scoreboard](/docs/scoreboard#build-a-box-score) joins the lines to player names and adds up team totals.

## Rosters

`GET /v1/{league}/games/{id}/roster` lists every player in the box score, with their team, jersey, position (`G`, `F` or `C`) and whether they started. A player who didn't play is on the roster but has no box-score line.

## What isn't filled yet

| Data                                   | What you get today                                                      |
| -------------------------------------- | ----------------------------------------------------------------------- |
| Injuries                               | `GET /v1/{league}/injuries` returns an empty list in all three leagues. |
| `clock_running` on the live state      | `null`. Use `status` and `clock_seconds`.                               |
| Timeouts and fouls in most NCAAB games | `null`, because the feed doesn't track them                             |

[Coverage by league](/docs/coverage#not-filled-yet) lists the gaps every sport shares, such as team totals and the score by period.

## League differences

|                                      | NBA                                                      | WNBA                            | NCAAB                                      |
| ------------------------------------ | -------------------------------------------------------- | ------------------------------- | ------------------------------------------ |
| Periods                              | Four 12-minute quarters                                  | Four 10-minute quarters         | Two 20-minute halves                       |
| `plus_minus`                         | Yes                                                      | Yes                             | No                                         |
| Blocks and steals in plays           | On the shot and the turnover, as `blocker` and `stealer` | As in the NBA                   | Often their own `block` and `steal` events |
| Timeouts and fouls on the live state | Reported when the feed has them                          | Reported when the feed has them | Usually `null`                             |
| Season `year`                        | The year the season starts, so 2026-27 is `2026`         | The year it's played            | The year the season starts                 |

NBA play-in games belong to the postseason, so their season's `type` is `PST`.