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

# Football

> How Statpad describes NFL and college football games, including the football live state, play types, drives, box score stat codes and the differences between the NFL and NCAAF.

The NFL (`nfl`) and NCAA Division I FBS football (`ncaaf`) share one data model. A game in either league fills the same endpoints and the same `football` blocks, so the same code reads both. The few fields that differ are under [NFL and NCAAF](#nfl-and-ncaaf).

The examples come from two recorded games: the Bills at the Vikings in the NFL, from [Sample responses](/docs/replay), and [Arkansas at Auburn](https://statpad.dev/samples/ncaaf-arkansas-at-auburn/plays.json) in NCAAF.

## Live state

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

| Field                                              | What it is                                                                                                               |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `period`                                           | The quarter, 1 to 4. A later period is an overtime.                                                                      |
| `clock_seconds`                                    | Seconds left in the quarter. The football feed moves the clock only when a play posts, so it doesn't tick between plays. |
| `clock_running`                                    | Always `null`. The football 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.                                         |
| `football.down`                                    | The down, 1 to 4.                                                                                                        |
| `football.yards_to_go`                             | Yards to a first down.                                                                                                   |
| `football.yardline`                                | The line of scrimmage, 0 to 100 from the possessing team's own goal line. 95 is the opponent's 5.                        |
| `football.home_timeouts`, `football.away_timeouts` | Timeouts each team has left in the half.                                                                                 |

After the final, the last down, distance and yard line stay. The timeouts are `null`, because the feed stops reporting them. [Sample responses](/docs/replay#a-game-in-progress) shows a whole football live state from the 4th quarter.

## Periods and overtime

Both leagues have a `period_kind` of `quarter` and 4 `regulation_periods`. Every period after the 4th is an overtime. [Build a scoreboard](/docs/scoreboard#the-period) turns a period number into a label such as `4th quarter` or `OT`, and [the clock section](/docs/scoreboard#the-clock) formats `clock_seconds`.

## Plays

`GET /v1/{league}/games/{id}/plays` lists every play. It returns a page of plays, 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 `football.play_type` are the same value, one of these:

| `play_type`                     | The play                                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `pass`                          | A pass, including sacks and interceptions                                                                                                   |
| `rush`                          | A run                                                                                                                                       |
| `punt`, `kickoff`, `field_goal` | A kick                                                                                                                                      |
| `extra_point`, `two_point`      | A try after a touchdown, filed as its own play. The feed often adds the try to the touchdown play instead, with the kicker as `pat_scorer`. |
| `penalty`                       | A play the feed files as a penalty, such as a false start                                                                                   |
| `kneel`, `spike`                | A kneel-down or a spike                                                                                                                     |
| `timeout`                       | A timeout, official timeouts included                                                                                                       |
| `other`                         | Anything else, such as the end of a quarter or the two-minute warning                                                                       |

The `football` block on each play:

| Field                                           | What it is                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `down`, `yards_to_go`                           | The down and distance before the snap.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `start_yardline`, `end_yardline`                | Where the play started and ended, 0 to 100 from the offense's own goal line. Read `end_yardline` for where this play ended rather than adding up yards. It isn't always where the next play starts: after a touchdown at 100, the kickoff starts at 35. The next play's `start_yardline` says where it starts. On a kick, the offense is the kicking team. On a turnover, `end_yardline` is the new offense's spot, still counted from the snapping team's goal line. |
| `yards_gained`                                  | What the play itself gained. It's `0` when a penalty wiped the play out.                                                                                                                                                                                                                                                                                                                                                                                              |
| `penalty_yards`                                 | Net yards that penalties moved the ball, for (+) or against (-) the offense. On a run, a pass or another scrimmage play whose start, end and gain are all known, `start_yardline + yards_gained + penalty_yards = end_yardline`. Otherwise, as on a kick or a turnover, it's the foul's stated yardage, so the sum doesn't hold. `null` without a penalty.                                                                                                            |
| `is_first_down`, `is_touchdown`, `is_turnover`  | What the play produced.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `is_penalty`                                    | A foul on the play was enforced or offset. A play whose only foul was declined has `false`.                                                                                                                                                                                                                                                                                                                                                                           |
| `air_yards`                                     | How far past the line of scrimmage the receiver caught the ball, negative behind it. Set on completed NFL passes only, and `null` on every other play.                                                                                                                                                                                                                                                                                                                |
| `play_action`, `screen_pass`, `run_pass_option` | Deprecated and always `null`. No provider reports them.                                                                                                                                                                                                                                                                                                                                                                                                               |

Each play's `participants` lists the players in it with a `role`: `passer`, `rusher`, `receiver`, `tackler`, `assist_tackler` (each player sharing a tackle), `sacker`, `pass_defender`, `kicker`, `punter`, `returner`, `holder`, `snapper`, `scorer`, `pat_scorer` (who scored the try), `pat_passer`, `pat_rusher`, `fumbler`, `fumble_forcer`, `recoverer`, `penalized`, or `player` for any other part. A player can have several roles on one play.

A player who isn't on the game's roster, such as a long snapper the feed doesn't list, isn't in `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. During a live game, a play can arrive with an empty or partial list and fill in on a later version. The recorded NFL sample's plays all have an empty list, because Statpad recorded that game before football plays listed their players.

`description` is the feed's play text. Read the structured fields rather than parsing it.

## Drives

`GET /v1/{league}/games/{id}/play-groups` lists the game's drives, each with `kind` set to `drive`. A play's `group_id` is the id of its drive. In both samples, every play has one, timeouts and the ends of quarters included.

This is the Bills' first touchdown drive in the NFL sample, from [`play-groups.json`](https://statpad.dev/samples/nfl-bills-at-vikings/play-groups.json), unedited:

```json
{
  "football": {
    "duration_seconds": 198,
    "end_clock": 44,
    "end_yardline": 100,
    "first_downs": 4,
    "play_count": 8,
    "points": 7,
    "start_clock": 242,
    "start_yardline": 20,
    "yards": 80
  },
  "game_id": "01a1d60f-67be-7bdd-83f4-53286521d9bb",
  "id": "01a1d60f-762a-7889-b486-a3f704982cf9",
  "kind": "drive",
  "period": 2,
  "period_half": null,
  "result": "Touchdown",
  "sequence": 13,
  "team_id": "01a1d60f-67be-7bdf-ac2f-bcdeeac1da68",
  "updated_at": "2026-11-13T17:58:20.485009Z",
  "version": 12
}
```

The Bills went 80 yards in 8 plays and 3:18, from their own 20 into the end zone, between 4:02 and 0:44 of the 2nd quarter. `team_id` is the team with the ball, and the yard lines count from that team's own goal line, so 100 is the end zone it attacks. `start_clock` and `end_clock` are seconds left in the period, and `duration_seconds` is the time of possession.

`result` is the feed's own wording for how the drive ended. The two samples have `Touchdown`, `Field Goal`, `Missed FG`, `Punt`, `Downs`, `Interception`, `Fumble`, `End of Half` and `End of Game`. Treat it as display text, because the feed can send other values.

## Box score

`GET /v1/{league}/games/{id}/boxscore` has one line per player. Each line's `stats` holds categories, and each category holds stat codes:

| Category                       | Stat codes                                                                                                                               |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `passing`                      | `att`, `completions`, `yards`, `yards_per_attempt`, `touchdowns`, `interceptions`, `qbr`; NFL also `rating`, `sacks`, `sack_yards_lost`  |
| `rushing`                      | `att`, `yards`, `yards_per_attempt`, `touchdowns`, `longest`                                                                             |
| `receiving`                    | `receptions`, `yards`, `yards_per_reception`, `touchdowns`, `longest`; NFL also `targets`                                                |
| `defensive`                    | `tackles`, `solo_tackles`, `sacks`, `tackles_for_loss`, `passes_defended`, `touchdowns`; NFL `qb_hits`, NCAAF `qb_hurries`               |
| `interceptions`                | `interceptions`, `yards`, `touchdowns`                                                                                                   |
| `fumbles`                      | `fumbles`, `lost`, `recovered`                                                                                                           |
| `kicking`                      | `field_goals_made`, `field_goal_attempts`, `field_goal_pct`, `longest_field_goal`, `extra_points_made`, `extra_point_attempts`, `points` |
| `punting`                      | `punts`, `yards`, `gross_average`, `inside_20`, `touchbacks`, `longest`                                                                  |
| `kick_returns`, `punt_returns` | `returns`, `yards`, `yards_per_return`, `longest`, `touchdowns`                                                                          |

`field_goal_pct` is a percentage, so 3 of 3 is `100`. A code the feed leaves out for a game, such as `qbr` in the NFL sample, is missing from the line. A player only has the categories that apply to them, so treat every category and code as optional. [Build a scoreboard](/docs/scoreboard#build-a-box-score) joins the lines to player names and adds up team totals.

## Rosters and injuries

`GET /v1/{league}/games/{id}/roster` lists every player the feed's box score names, with their team and jersey. That can include a player with no stat line. The football feed has no game positions or starters, so `position` is `null` and `starter` is `false`.

`GET /v1/nfl/injuries` has the NFL injury report. [Coverage by league](/docs/coverage#field-notes) describes the injury fields. NCAAF has no injuries.

## What isn't filled yet

These football fields are part of the API, but nothing fills them today:

| Field                                                       | What you get today                                                                                           |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `play_action`, `screen_pass` and `run_pass_option` on plays | Always `null`, because no provider reports them. They stay in the response so existing parsers keep working. |
| `clock_running` on the live state                           | `null`. Use `status` and `clock_seconds`.                                                                    |
| `position` and `starter` on a game roster entry             | `null` and `false`                                                                                           |
| `primary_position` on players                               | `null`, except for NFL players who have been on the injury report                                            |
| NCAAF injuries                                              | An empty list                                                                                                |

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

## NFL and NCAAF

The two leagues differ in a few fields:

|                    | NFL                                          | NCAAF                                                                      |
| ------------------ | -------------------------------------------- | -------------------------------------------------------------------------- |
| `air_yards`        | Set on completed passes                      | Always `null`, because the college feed has no yards after the catch       |
| Passing codes      | Adds `rating`, `sacks` and `sack_yards_lost` | No `rating`, `sacks` or `sack_yards_lost`                                  |
| Receiving codes    | Adds `targets`                               | No `targets`                                                               |
| Defensive codes    | `qb_hits`                                    | `qb_hurries`                                                               |
| Injuries           | Filled                                       | Not filled                                                                 |
| Play `description` | The play text                                | The play text, which usually starts with the game clock, such as `(13:49)` |