> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akaramarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Football
> Event vocabulary and game state for the football feed — NFL
The football feed covers live NFL games. Feed reads carry no sport in the URL — the [catalog](/api-reference/catalog), [WebSocket](/api-reference/websocket), [history backfill](/api-reference/history), and [session health](/api-reference/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](/sports/overview) for the conventions and cross-sport events (`score_set`, `game_end`, `undo`) shared across every sport.
### Score
| Field | Type | Description |
| ------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `score` | `{ a: number, b: number }` | Running score, derived from events. Increases on `touchdown` (+6), `extra_point` (+1), `two_point_conversion` (+2), `field_goal` (+3), and `safety` (+2); decreased by `touchdown_nullified` (−6); overwritten by `score_set` |
| `final` | boolean | `true` once the game ends — no further frames will arrive |
### Possession
| Field | Type | Description |
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `possession` | string \| null | Which side has the ball — `"A"`, `"B"`, or `null` before the first assignment. Set only by `possession` (scheduled changes) and `turnover` (live takeaways) |
### Quarter
| Field | Type | Description |
| -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `period` | integer | Current quarter (1-indexed). Overtime is simply `period > 4`. Advances when a `period_end` is followed by the next play-open (`snap`/`kickoff`); `period` events set it absolutely |
### Field position
Coarse thirds plus a red-zone flag — the leverage gradient, not a yard line. `null` until the first `location` press.
| Field | Type | Description |
| --------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `zone` | string \| null | Which third of the field the ball is in. See [Zone values](#zone-values) |
| `redZone` | boolean | Ball inside the 20 of the side third named by `zone` (only meaningful on `"a_side"`/`"b_side"`) |
### Play span and pre-snap reads
| Field | Type | Description |
| ----------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `live` | boolean | A play is open — set by `snap`/`kickoff`, closed by `end` or by a scoring resolution (`touchdown`, `extra_point`, `two_point_conversion`, `field_goal`, `safety` — the ball is dead by rule the instant the outcome exists). `false` at rest |
| `deepBall` | boolean | A deep pass is in the air on the current play. Set by `deep_ball`; subordinate to `live` — clears the instant the play resolves. `false` at rest |
| `bigPlay` | boolean | A breakaway is in progress on the current play. Set by `big_play`; subordinate to `live` — clears the instant the play resolves (it rides a `turnover`'s return, which keeps the play live). `false` at rest |
| `looseBall` | boolean | The ball is loose on the current play — a strip, a muff, a botched snap or hold, or a carrier crossing the line of scrimmage — possession is genuinely undecided while `true`. Set by `loose_ball`; cleared by `turnover` (the defense recovered — the takeaway is the resolution) or by any play close (the offense kept it). `false` at rest |
| `formation` | string \| null | The armed pre-snap unit read — see [Formation values](#formation-values). Cleared when the play opens |
| `flagOpen` | boolean | A penalty flag is down and unresolved. **While `true`, score changes on the current play are provisional** — a `touchdown_nullified` may follow |
***
## 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"`.
| Value | Meaning |
| ---------- | ---------------------------------------------- |
| `"a_side"` | The third of the field containing A's end zone |
| `"mid"` | The middle band of the field |
| `"b_side"` | The third of the field containing B's end zone |
### Formation values
| Value | Meaning |
| ----------------- | -------------------------------------------------------------------------------------- |
| `"punt_unit"` | The punt team is on the field — a punt is coming |
| `"fg_unit"` | The field-goal unit is on — a kick is coming (after a touchdown: the extra-point kick) |
| `"offense_stays"` | The offense stays out — going for it on 4th down (after a touchdown: going for two) |
***
## 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.
```json theme={null}
{ "type": "snap", "payload": {} }
```
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.
```json theme={null}
{ "type": "kickoff", "payload": {} }
```
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.
```json theme={null}
{ "type": "end", "payload": {} }
```
A timeout, team or official. Asserts the ball is dead. The feed does not track timeout counts.
No payload fields.
```json theme={null}
{ "type": "timeout", "payload": {} }
```
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.
```json theme={null}
{ "type": "period_end", "payload": {} }
```
***
### 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.
| Field | Type | Description |
| ------ | ------ | ----------------------------------------------- |
| `team` | string | `"A"` or `"B"` — the side that now has the ball |
```json theme={null}
{ "type": "possession", "payload": { "team": "B" } }
```
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.
| Field | Type | Description |
| ------ | ------ | --------------------------------------------------- |
| `team` | string | `"A"` or `"B"` — the side that **now** has the ball |
```json theme={null}
{ "type": "turnover", "payload": { "team": "A" } }
```
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`.
| Field | Type | Description |
| ---------- | ------- | -------------------------------------------------------------------- |
| `zone` | string | `"a_side"`, `"mid"`, or `"b_side"` — see [Zone values](#zone-values) |
| `red_zone` | boolean | Ball inside the 20 of the stated side third |
```json theme={null}
{ "type": "location", "payload": { "zone": "b_side", "red_zone": true } }
```
***
### 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.
```json theme={null}
{ "type": "deep_ball", "payload": {} }
```
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.
```json theme={null}
{ "type": "big_play", "payload": {} }
```
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.
```json theme={null}
{ "type": "loose_ball", "payload": {} }
```
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.
| Field | Type | Description |
| ------ | ------- | ---------------------------------------------- |
| `team` | string | `"A"` or `"B"` — the side whose player is down |
| `qb` | boolean | The downed player is the quarterback |
```json theme={null}
{ "type": "player_down", "payload": { "team": "A", "qb": true } }
```
***
### 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).
| Field | Type | Description |
| ------ | ------ | --------------------------------- |
| `team` | string | `"A"` or `"B"` — the scoring side |
```json theme={null}
{ "type": "touchdown", "payload": { "team": "A" } }
```
+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.
| Field | Type | Description |
| ------ | ------ | -------------------------------------------- |
| `team` | string | `"A"` or `"B"` — the side attempting the try |
```json theme={null}
{ "type": "extra_point", "payload": { "team": "A" } }
```
+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.
| Field | Type | Description |
| ------ | ------ | ---------------------------------- |
| `team` | string | `"A"` or `"B"` — the side credited |
```json theme={null}
{ "type": "two_point_conversion", "payload": { "team": "B" } }
```
+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.
| Field | Type | Description |
| ------ | ------ | --------------------------------- |
| `team` | string | `"A"` or `"B"` — the kicking side |
```json theme={null}
{ "type": "field_goal", "payload": { "team": "B" } }
```
+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.
| Field | Type | Description |
| ------ | ------ | ------------------------------------------------ |
| `team` | string | `"A"` or `"B"` — the side credited (the defense) |
```json theme={null}
{ "type": "safety", "payload": { "team": "B" } }
```
***
### 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.
```json theme={null}
{ "type": "flag", "payload": {} }
```
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.
```json theme={null}
{ "type": "flag_resolve", "payload": {} }
```
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.
| Field | Type | Description |
| ------ | ------ | --------------------------------------------------- |
| `team` | string | `"A"` or `"B"` — the side whose touchdown was wiped |
```json theme={null}
{ "type": "touchdown_nullified", "payload": { "team": "A" } }
```
***
### 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.
```json theme={null}
{ "type": "fg_unit", "payload": {} }
```
***
### Corrections
Overwrites both totals. Scoring continues from the new values.
| Field | Type | Description |
| ----- | ------- | -------------------- |
| `a` | integer | New score for side A |
| `b` | integer | New score for side B |
```json theme={null}
{ "type": "score_set", "payload": { "a": 21, "b": 17 } }
```
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.
| Field | Type | Description |
| -------- | ------- | ------------------------------ |
| `period` | integer | The quarter (overtime is `5`+) |
```json theme={null}
{ "type": "period", "payload": { "period": 3 } }
```
Terminal: sets `final`. Consumers should close the WebSocket after receiving this — no further frames will arrive.
No payload fields.
```json theme={null}
{ "type": "game_end", "payload": {} }
```
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.
```json theme={null}
{ "type": "undo", "payload": { "retractsSeq": 41 } }
```