- REST — as
live_game_stateon event responses. - WebSocket — inside score frames (
meta.type=score) on thelivechannel. A score frame is published whenever the game state changes, including when nothing else about the score changed.
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 records the observation time of an accepted change to display_clock, clock_seconds or clock_running. Re-observing the same values preserves that timestamp, so its age alone cannot distinguish a paused clock from a stale observation.
A change to clock_running can advance clock_as_of while the displayed clock stays the same. Read clock_running for the reported running state; timestamp movement alone does not establish whether the clock stopped or resumed.
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
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’sscore object, which carries event_status, event_status_detail and game_period. See Event Statuses for the full list.
Play-by-play timeline
The play timeline is available throughGET /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.Amended and removed plays
These flags appear only on stream frames (theplays and live WebSocket channels), inside data.data:
Both are omitted on ordinary plays. A play that arrives late for the first time is not flagged:
sequence is assigned in arrival order, so a late play has a higher sequence than plays with a later game clock in the same period. GET /api/v2/events/{eventID}/plays returns each play’s current state and does not carry these flags.
Ordering the timeline
Order bysequence, 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.
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 for subscribing to the
livechannel - Event Statuses
- Game Stats for team and player box-score deltas