Skip to content
Product Documentation

game-state-timeline

The reconstructed state of a game over wall-clock time — what the score was, what period it was, what the clock read — as a flat list of timestamped observations. Join it against odds records (e.g. sportsbook-lines timestamp) to know the game context behind any line move.

Fetching

Section titled “Fetching”
Terminal window
curl -s "https://api.betflux.ai/v1/games/NBA_GSW_MIA_20260401/game-state-timeline" \
  -H "Authorization: Bearer $BETFLUX_API_KEY" -o timeline.parquet
Terminal window
betflux get game-state-timeline --game NBA_GSW_MIA_20260401

Per-game only — the grain is the game, so there are no date-range pulls. game_id is the public id. This is the one dataset that is not history-gated: any tier can fetch any covered game.

Row shape

Section titled “Row shape”

One row per observation:

  • ts is the observation timestamp as epoch milliseconds UTC (int64) — absolute time, directly comparable to any other timestamp you hold.
  • Observations are change-only: a field appears when its value changed.
  • field values are stable snake_case names such as home_score, away_score, period, clock; value is the observed value stringified (cast it per field), and null when the field was cleared.
  • source is provenance — MSF (the stats feed) or a sportsbook operator code — worth weighing when observations disagree.

Columns

Section titled “Columns”
ColumnTypeNullableDescription
game_idstringnoPublic game id: LEAGUE_AWAY_HOME_YYYYMMDD (ET date; `_2` suffix for the second game of a doubleheader).
leaguestringnoLeague code, e.g. NBA, NFL, MLB, NHL.
game_datestringnoCalendar date of the scheduled start in US Eastern time (Parquet date, YYYY-MM-DD).
tsintegernoObservation timestamp, epoch milliseconds UTC (int64; renamed from the gold column ts_ms).
fieldstringnoStable snake_case state field, e.g. home_score, period, clock.
valuestringyesObserved value, stringified; null when the field was cleared.
sourcestringnoObservation source, e.g. MSF or a sportsbook operator code.

Coverage

Section titled “Coverage”

MLB, NBA, NHL, and NFL (no NCAAM). Reconstruction quality varies by source coverage for a given game — treat source as provenance when weighing observations.