games

One row per game. This is both the discovery surface — the id is the readable public game id every per-game dataset endpoint takes — and the game record: when and where it is played, who is playing, the score as it stands, and the weather at the venue.

Fetching

curl -s "https://api.betflux.ai/v1/games?league=MLB&date_from=2026-07-01&date_to=2026-07-07" \
  -H "Authorization: Bearer $BETFLUX_API_KEY"

curl -s "https://api.betflux.ai/v1/games/MLB_BOS_NYY_20260715" \
  -H "Authorization: Bearer $BETFLUX_API_KEY"

betflux games --league MLB --date-from 2026-07-01 --date-to 2026-07-07
betflux games --id MLB_BOS_NYY_20260715 --format record

games = bf.games(league="MLB", date_from="2026-07-01", date_to="2026-07-07")
game = bf.game("MLB_BOS_NYY_20260715")

Parameter	Meaning
`league`	One league code
`date_from`, `date_to`	Inclusive ET game dates (`YYYY-MM-DD`); give both or neither, at most 366 days apart
`team`	Canonical team name; matches home or away
`status`	`SCHEDULED`, `DELAYED`, `STARTED`, `SUSPENDED`, `COMPLETED`, `POSTPONED`
`limit`, `cursor`	Pagination

Sorted by start time, then id. The single-game route takes the public id only (case-insensitive); a UUID is a 404.

Semantics

Ids. LEAGUE_AWAY_HOME_YYYYMMDD, ET date, _2 for the second game of a doubleheader — see Core concepts. game_date is that same ET date; start_time is the scheduled start in UTC and moves if the game is rescheduled.
Status and score are current state. status and is_live flip as the game is played; home_score / away_score, current_period, the clock, and the per-period line scores update while it is live and are final once status is COMPLETED. Before tip-off they are null (the line-score arrays are empty). Each value is the latest state, refreshed a few times an hour — for the history of these fields over the course of the game use game-state-timeline.
Periods are sport-neutral. current_period is the quarter (NBA, NFL, NCAAF), inning (MLB), period (NHL), or half (NCAAM); current_period_half is MLB’s TOP / BOTTOM; current_period_seconds_remaining is set for timed sports only. period_scores_home and period_scores_away are index-aligned — entry i is period i + 1 — and extend through overtime or extra innings.
Venue. venue_* describes where the game is played: name, city with its region (e.g. Atlanta, GA), country, coordinates, the building’s largest sports capacity, playing surface, and roof. is_neutral_venue marks neutral-site games. The fields are null when no venue is known.
Weather is the game-time forecast at the venue, in US units, refreshed on game day. It is null indoors (most arenas), for NCAAF, and before a forecast exists. Domes can still carry an outdoor forecast for the stadium’s location — check venue_has_roof.
Schedule extras. week is set for NFL and NCAAF; attendance and end_time appear after the game when known (end_time is often never set); delayed_or_postponed_reason is populated while status is DELAYED or POSTPONED; broadcasters lists outlets when known, otherwise it is empty.
Team fields are denormalized from teams: the UUIDs are the join keys, the names and abbreviations are display conveniences.

Columns

Column	Type	Nullable	Description
`id`	`string`	no	Game id (e.g. NBA_GSW_MIA_20250408).
`league`	`string`	no	League code, e.g. NBA, NFL, MLB, NHL, NCAAM, NCAAF.
`game_date`	`string`	no	Eastern-Time calendar date of the scheduled start (matches closing-lines game_date).
`start_time`	`string`	no	Scheduled start, ISO 8601 UTC.
`status`	`string`	no	Schedule status, e.g. SCHEDULED, STARTED, COMPLETED.
`is_live`	`boolean`	no	True while the game is in progress.
`home_team`	`string`	no	Canonical home team name.
`home_team_abbr`	`string`	no	Home team abbreviation, e.g. MIA.
`home_team_id`	`string`	no	Canonical home team UUID (matches /v1/teams ids).
`away_team`	`string`	no	Canonical away team name.
`away_team_abbr`	`string`	no	Away team abbreviation, e.g. GSW.
`away_team_id`	`string`	no	Canonical away team UUID (matches /v1/teams ids).
`season`	`string`	yes	Season slug the game belongs to, e.g. 2026-regular.
`season_type`	`string`	yes	PRESEASON, SEASON (regular) or POSTSEASON.
`end_time`	`string`	yes	Observed end, ISO 8601 UTC; null until known (often never set).
`week`	`integer`	yes	Schedule week (NFL, NCAAF); null for other leagues.
`is_neutral_venue`	`boolean`	no	True when neither team is the venue's home side.
`delayed_or_postponed_reason`	`string`	yes	Reason while status is DELAYED or POSTPONED; null otherwise.
`broadcasters`	`string[]`	no	Broadcast outlets; empty when unknown.
`attendance`	`integer`	yes	Reported attendance; null until posted.
`home_score`	`integer`	yes	Home score so far; final once status is COMPLETED. Null before tip-off.
`away_score`	`integer`	yes	Away score so far; final once status is COMPLETED. Null before tip-off.
`current_period`	`integer`	yes	Quarter / inning / period / half in progress; null before the game and after it ends.
`current_period_seconds_remaining`	`integer`	yes	Clock seconds left in the current period (timed sports); null otherwise.
`current_period_half`	`string`	yes	TOP or BOTTOM of the current inning (MLB); null elsewhere.
`current_intermission`	`string`	yes	Label for a break in play (e.g. HALFTIME); null while play is on.
`period_scores_home`	`integer[]`	no	Home line score, one entry per completed or in-progress period.
`period_scores_away`	`integer[]`	no	Away line score, index-aligned with period_scores_home.
`venue_id`	`string`	yes	Venue UUID; null when no venue is known.
`venue_name`	`string`	yes	Venue name, e.g. Truist Park.
`venue_city`	`string`	yes	Venue city with its region, e.g. Atlanta, GA.
`venue_country`	`string`	yes	Venue country, e.g. USA.
`venue_latitude`	`number`	yes	Venue latitude (WGS84).
`venue_longitude`	`number`	yes	Venue longitude (WGS84).
`venue_capacity`	`integer`	yes	Largest sports capacity of the building.
`venue_surface`	`string`	yes	Playing surface, e.g. Kentucky Bluegrass, FieldTurf; null when unknown.
`venue_has_roof`	`boolean`	yes	True for covered venues (domes and arenas).
`venue_has_retractable_roof`	`boolean`	yes	True when the roof can open.
`weather_type`	`string`	yes	Weather category at game time, e.g. SUNNY, CLOUDY, LIGHT_RAIN; null indoors or when unavailable.
`weather_description`	`string`	yes	Free-text weather description, e.g. sky is clear.
`weather_temperature_f`	`number`	yes	Temperature in °F.
`weather_wind_speed_mph`	`number`	yes	Wind speed in mph.
`weather_wind_direction_degrees`	`integer`	yes	Wind origin bearing in degrees.
`weather_wind_direction_label`	`string`	yes	Compass label for the wind origin, e.g. WSW.
`weather_precipitation_type`	`string`	yes	RAIN, SNOW, … when precipitation is forecast; null otherwise.
`weather_precipitation_percent`	`integer`	yes	Precipitation probability in percent.
`weather_humidity_percent`	`integer`	yes	Relative humidity in percent.