live-stats

Live NFL/NCAAF play-by-play

Descriptive play-by-play for one match, during the game and after it finishes. NFL, NCAAF and NCAAF FCS. Pro plan or higher. The shared NFL play-by-play gate protects this route alongside the american_football sport entitlement.

SOURCE, STATED RATHER THAN LEFT TO AN ORDERING. football_plays carries rows from two vendors; this endpoint serves ONLY the rows from our licensed paid aggregator. The other vendor's rows exist in storage as derivation input and are never served; that vendor's licence is redistribute: no, while the paid aggregator's all-sports redistribution grant (2026-09-09) covers this table's rows outright.

DIFFERENT TABLE FROM GET /v1/nfl/games/{gameId}/plays. That endpoint reads public_nfl_plays (EPA/WP, NFL only, rebuilt nightly, keyed on the league-standard text game id). This one reads football_plays (keyed on the same match UUID every other /v1/live-stats/* and /v1/matches/* endpoint uses), sourced from the paid aggregator and updated while a game is in progress. The two are never blended in one response; ask for both if you want both.

FRESHNESS. meta.as_of is the timestamp the freshest play last changed; meta.stale says whether we would expect to have learned something more recently than that. A feed that has stopped updating mid-game and one that is simply quiet are indistinguishable without those two fields.

get/v1/live-stats/american_football/{matchId}/plays

Request

  • Base URL: https://api.bigballsdata.com
  • URL: https://api.bigballsdata.com/v1/live-stats/american_football/{matchId}/plays
  • Auth: one of:
    • API key in header x-api-key
    • HTTP bearer

Path parameters

matchIdstring uuid required

Query parameters

scoring_onlyboolean

Return only plays where scoring_play is true. Accepted: true|1|yes|on and false|0|no|off; anything else is a 400 naming the parameter. false means OFF. Until 2026-09-20 every spelling of false was read as true, so opting OUT of the filter turned it ON.

Response

ok

Example response

{
  "data": {
    "sport": "american_football",
    "plays": [
      {
        "participants": [
          {
            "role": "field_goal_kicker"
          }
        ]
      }
    ]
  },
  "meta": {
    "source": "live-stats"
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.