Skip to main content
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. 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

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