> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therundown.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Live Game State
> Period, clock, and sport-specific in-game situation, plus the play-by-play timeline shape.
Live game state is the current in-game situation for an event: what period it is, what the clock reads, and the sport-specific detail that goes with it (down and distance in football, base runners in baseball, and so on).
It is available on **Ultra plans and higher**, and appears in two places:
* **REST** — as `live_game_state` on event responses.
* **WebSocket** — inside score frames (`meta.type=score`) on the **`live`** channel. A score frame is published whenever the game state changes, including when nothing else about the score changed.
The `scores` channel does **not** carry `live_game_state`; the field is stripped from score frames on that channel. Subscribe to `live` (or its `live_game_state` / `game_state` aliases) when you need the state surface over WebSocket.
Use the state surface, not the play timeline, when you need to know the current period or clock. The play timeline tells you what has already happened; the state object tells you where the game is right now.
## Sport-agnostic fields
These are present for every sport that has live game state.
| Field | Type | Description |
| ---------------- | ------- | ------------------------------------------------------------------ |
| `event_id` | string | The event this state belongs to. |
| `sport_id` | integer | Numeric sport ID. |
| `sport` | string | Sport slug, for example `nfl`, `nba`, `mlb`, `soccer`. |
| `period` | integer | Current period, quarter, inning, or half. |
| `half_indicator` | string | Present where the sport has a meaningful half or top/bottom split. |
| `display_clock` | string | The clock as shown, for example `12:00`. |
| `clock_seconds` | integer | The same clock in seconds. |
| `clock_running` | boolean | Whether the clock has been observed running. |
| `clock_as_of` | string | ISO 8601 timestamp of when that clock value was observed. |
| `last_play` | object | Compact reference to the most recent play. |
| `updated_at` | string | ISO 8601 timestamp of when this state row was last written. |
Every field except `event_id`, `sport_id`, `sport` and `updated_at` is omitted when it does not apply, so absence means "not applicable or not yet known" rather than zero. Sports without a game clock, such as tennis and baseball, do not carry the clock fields at all.
### Reading the clock correctly
`clock_as_of` advances **only when the observed clock value itself changes**. That gives you a way to tell a genuinely stopped clock from a stale reading:
* Clock unchanged, `clock_as_of` unchanged — nothing has moved since that timestamp.
* Clock unchanged, `clock_as_of` moving — the clock is confirmed stopped and still being observed.
`clock_running` reports that the clock **has been observed running again**. Treat it as a state confirmation rather than a whistle-accurate restart timestamp: it is the right signal for "play has resumed", but it is not a precise measurement of the moment the referee restarted play.
## Sport-specific blocks
The state object carries one nested block matching the event's sport. Fields inside are omitted when unavailable.
### `football` — NFL, NCAAF
| Field | Type | Description |
| -------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `possession_team_id` | integer | Team currently in possession. |
| `down` | integer | Current down. |
| `distance` | integer | Yards needed for a first down. |
| `yard_line` | integer | Numeric field position. |
| `down_distance_text` | string | Human-readable down, distance and field position, for example `4th & 2 at DAL 18`. |
| `short_down_distance_text` | string | Down and distance only, for example `4th & 2`. |
| `possession_text` | string | Abbreviation of the team in possession. |
| `is_red_zone` | boolean | Whether the offense is inside the opponent's 20. |
| `home_timeouts` | integer | Home team timeouts remaining. |
| `away_timeouts` | integer | Away team timeouts remaining. |
**For field position, read `down_distance_text`.** It is the only field that states which team's side of the field the ball is on. `possession_text` names the team **with the ball**, which is frequently not the team whose territory they are in: a drive at `4th & 2 at DAL 18` may well have Philadelphia in possession. There is no separate side-of-field identifier, so `yard_line` on its own does not tell you which half of the field you are in.
### `basketball` — NBA, WNBA, NCAAB
`possession_team_id`, `home_timeouts`, `away_timeouts`, `home_in_bonus`, `away_in_bonus`.
### `hockey` — NHL
`possession_team_id`, `strength`, `power_play_team_id`, `home_shots_on_goal`, `away_shots_on_goal`.
### `mlb`
`balls`, `strikes`, `outs`, `on_first`, `on_second`, `on_third`, `current_batter`, `current_pitcher`.
### `soccer`
Possession percentages and shot counts for both sides.
## Event status is sport-specific
Live game state sits alongside the event's `score` object, which carries `event_status`, `event_status_detail` and `game_period`. See [Event Statuses](/reference/event-statuses) for the full list.
The status vocabulary **differs by sport**. A soccer match in play reports `STATUS_FIRST_HALF`, not `STATUS_IN_PROGRESS`, while tennis reports `STATUS_IN_PROGRESS`. Do not assume one sport's status set applies to another, and treat any value you do not recognize as unknown rather than an error, since new values are added over time.
For detecting period transitions, keying off `live_game_state.period` and the clock fields is more portable than matching status strings.
## Play-by-play timeline
The play timeline is available through `GET /api/v2/events/{eventID}/plays` and streams on the `plays` and `live` channels.
| Field | Type | Description |
| --------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `play_id` | integer | Stable identity for the play. Use this as your key. |
| `sequence` | integer | Position of the play in the timeline. |
| `period` | integer | Period the play belongs to. |
| `type` | string | Play type slug, for example `rush`, `kickoff`, `timeout`. |
| `description` | string | Human-readable description. |
| `display_clock` | string | Clock **at the moment the play happened**, frozen thereafter. |
| `occurred_at` | string | ISO 8601 timestamp of when the play happened. |
| `team_id` | integer | Team the play belongs to. |
| `scoring_play` | boolean | Whether the play scored. |
| `score_value` | integer | Points scored on the play. |
| `score_away_after` / `score_home_after` | integer | Score after the play. |
| `participants` | array | Players involved, where attribution is available. |
| `football` | object | Football extras: `start_yard_line`, `end_yard_line`, `stat_yardage`, `drive_description`. |
`display_clock` on a play is the clock **at that play**, deliberately frozen. The live clock is `display_clock` on `live_game_state`. The two are different fields with different meanings.
### Ordering the timeline
**Order by `sequence`, not by `occurred_at`.**
Most entries carry a real observed timestamp. Structural markers, however, are timeline bookkeeping rather than plays with a moment of their own, and their `occurred_at` is anchored to the play they follow rather than independently observed. `sequence` is the authoritative order in every case.
The structural markers are `coin_toss`, `end_period`, `end_of_half` and `end_of_game`.
Structural markers are **not real-time signals**. They are written to the timeline after the fact, so they are not suitable for detecting a period boundary as it happens. To react to a quarter or half beginning or ending, watch `live_game_state.period` and the clock fields on the state surface instead.
### Common football play types
`rush`, `pass_reception`, `pass_incompletion`, `sack`, `penalty`, `kickoff`, `punt`, `field_goal_good`, `field_goal_missed`, `passing_touchdown`, `timeout`, `official_timeout`, `two_minute_warning`, `fumble_recovery_(own)`, `muffed_punt_recovery_(opponent)`, `coin_toss`, `end_period`, `end_of_half`, `end_of_game`.
This list is not exhaustive and new values appear over time, so treat an unrecognized `type` as unknown rather than an error.
`timeout` and `official_timeout` are distinct types and both carry real timestamps, so they are reliable for detecting stoppages. To detect play resuming afterwards, watch `clock_running` return to true on the state surface.
## Related
* [Multiplexed WebSocket](/guides/multiplexed-websocket) for subscribing to the `live` channel
* [Event Statuses](/reference/event-statuses)
* [Game Stats](/api-reference/v2/stats) for team and player box-score deltas