Skip to main content
The football feed covers live NFL games. Feed reads carry no sport in the URL — the catalog, WebSocket, history backfill, and session health are all top-level endpoints addressed by session id.
Football is a discrete-play sport: each play spans snap (or kickoff) → end, with a long dead window between plays. The feed leans on that structure — the play-open press is your earliest “an outcome may be imminent” warning, in-flight flags (deepBall, bigPlay, looseBall) mark the open-outcome seconds, and a penalty flag freezes everything seen on the play until enforcement resolves it.

​
Game state

Every WebSocket frame carries a full FootballState snapshot. The history backfill returns events only — to rebuild this state from the log, replay the events; each event’s entry below specifies its exact effect on state. Fields are camelCase on the wire. See the Sports overview for the conventions and cross-sport events (score_set, game_end, undo) shared across every sport.

​
Score

​
Possession

​
Quarter

​
Field position

Coarse thirds plus a red-zone flag — the leverage gradient, not a yard line. null until the first location press.

​
Play span and pre-snap reads

​
Enum values

​
Zone values

Sides are absolute: "a_side" is the third containing side A’s end zone (side A defends it — whoever attacks there threatens A), and likewise "b_side".

​
Formation values

​
Events

The play-open press is deliberately early and outcome-free; results arrive as their own presses in the dead window after the whistle. The in-flight flags (deep_ball, big_play, loose_ball) set deepBall / bigPlay / looseBall on the snapshot while the play is live and clear when the play resolves — so you can react to them off the state, not only the event, and they self-clear rather than needing a decay timer.

​
Play lifecycle

The ball is snapped — the earliest warning that an outcome may be imminent. Sets live, clears the armed formation read, and (after a period_end) commits the quarter advance.No payload fields.
A kickoff or free kick is away — the play opens without a snap. Identical state effects to snap; a separate type because it reads differently on the tape (a kickoff follows every score and opens every half). An onside-kick recovery arrives as turnover.No payload fields.
Closes the play span (live → false) — the safe-to-requote signal. A known outcome (a turnover) is pressed before end, so by the time it arrives the tape reflects everything knowable at the whistle; only genuinely late rulings (a pile-up recovery) follow it. Sent for plays without a scoring resolution — touchdown, extra_point, two_point_conversion, field_goal, and safety close the span themselves, and an end after one of those may or may not appear (it is a harmless no-op).No payload fields.
A timeout, team or official. Asserts the ball is dead. The feed does not track timeout counts.No payload fields.
The quarter ended. period still holds the quarter that just finished — that is which period ended (a period_end at period: 2 is halftime). The next snap/kickoff advances period. Overtime needs no special handling: a period_end at period: 4 followed by a play-open yields period: 5.No payload fields.

​
Possession and field position

Sets the possession axis. Used for the scheduled exchanges — a punt received, a kickoff fielded, a turnover on downs. Live-ball takeaways use turnover instead.
An interception or a loose ball recovered by the defense — sent the moment the new possession is known: instantly on a pick, at the scramble’s resolution after a loose_ball. Sets possession to the stated side and clears an open looseBall flag (the takeaway is its resolution). The play span stays open — the return is still running. The takeaway kind is readable from the sequence: loose_ball → turnover is a recovered loose ball, a bare turnover is an interception. A blocked field goal returned also arrives this way — field_goal is only pressed on a make.
Where the ball is: a field third plus the red-zone flag. Ambient context — never moves score, possession, or the play span; superseded by the next location.

​
In-flight signals

Several seconds of hang time in which the play’s outcome is genuinely open. Sets deepBall on the snapshot while the play is live and clears the instant it resolves (the outcome then arrives as its own press — touchdown, turnover, end). Read it off the state, not just the event: it self-clears, no decay timer needed. Carries no team: the thrower is the possession axis.No payload fields.
A runner through the second level, a return with blockers, a scramble turning into a chunk gain. Sets bigPlay with the same contract as deep_ball — subordinate to live, cleared when the play resolves (so it rides a turnover’s return, which keeps the play live).No payload fields.
The ball is out of a carrier’s hands and up for grabs — a strip, a muffed punt, a botched snap or hold, or a carrier crossing the line of scrimmage. Sets looseBall on the snapshot: possession is genuinely undecided until the flag clears. Resolution reuses the rest of the vocabulary — a turnover means the defense recovered (and clears the flag), while a play close with no turnover means the offense kept it. An interception arrives as a bare turnover with no loose_ball before it, so the two takeaway kinds are distinguishable from the sequence.No payload fields.
A player is staying down. qb: true marks the one identity that reprices a game on its own; finer identity is out of scope. No state effect — the stoppage arrives as its own clock presses.

​
Scoring

Credits +6 to the stated side the moment the scout sees the score — provisional while a flag is open (flagOpen: true): a touchdown_nullified may follow. The side is explicit because a defensive return scores for the defense. Closes the play span (live → false — a touchdown ends the play by rule; no end follows).
+1 to the stated side, credited the moment the kick is good. Which kind of try was attempted already arrived as the formation read before the try (fg_unit). A failed kick emits no event — the play simply closes on end. Closes the play span.
+2 to the stated side, credited the moment the conversion is good. Which kind of try was attempted already arrived as the formation read before the try (offense_stays). The side is explicit because a defensive return scores for the defense. A failed conversion emits no event — the play simply closes on end. Closes the play span.
+3 to the stated side, credited the moment the kick is good — mirrors touchdown: a single immediate score, not an open/resolve pair. The side is explicit — there is no latched attempt to inherit from. A miss emits no event: it is signaled only by the following turnover (a blocked kick returned) or end (no return). A snap under an fg_unit formation read is the “kick coming” cue. Closes the play span.
+2 to the stated side — the defense (a safety scores against the side with the ball, which is why the team is explicit). The free kick that follows arrives as kickoff + possession. Closes the play span.

​
Flags

Sets flagOpen. Everything seen on this play — including a touchdown — is provisional until enforcement. The flag press fires when the cloth is visible, typically well before the referee announces what it is for. A second flag on the same play re-asserts harmlessly.No payload fields.
Clears flagOpen — the single close, sent whether the play stood, the penalty was declined, or the flag was picked up. The substance of an enforcement arrives as the correction events between flag and flag_resolve: a touchdown_nullified, a fresh possession, a location. A flag that changed nothing is simply flag → flag_resolve with nothing between.No payload fields.
A flag wiped the touchdown: −6 for the stated side. A real refereeing outcome, distinct from undo (scout error). Nullified field goals and safeties are rare enough that they arrive as score_set corrections instead.

​
Pre-snap formation reads

Before a 4th-down snap (or a try after a touchdown), the unit visibly taking the field announces the decision seconds before any broadcast graphic. Arms formation; the next play-open clears it. Three types, same shape:
  • punt_unit — the punt team is out.
  • fg_unit — the field-goal unit is out (after a touchdown: the extra-point kick).
  • offense_stays — the offense stays on: going for it (after a touchdown: going for two).
No payload fields.

​
Corrections

Overwrites both totals. Scoring continues from the new values.
Correction-only override for the quarter (routine rollover rides period_end → the next play-open). Also disarms a pending advance, so the next play-open will not additionally increment.
Terminal: sets final. Consumers should close the WebSocket after receiving this — no further frames will arrive.No payload fields.
Retracts the most recent scout press. Both the original press and the undo appear in /history as raw events — a client replaying the log resolves it there: each undo cancels the most recent non-undo event.The scout sends no payload fields; the served payload carries the server-stamped retractsSeq — the seq of the press the undo cancelled (null when nothing remained) — on the live frame and in /history alike, so a display can strike the retracted row without replaying.