Overview

The datasets are per-game Parquet files keyed by ids: a game id in the URL, team and player UUIDs in the columns. The reference data is the JSON side that resolves those ids — and, for games, the record of the game itself: schedule, teams, score, venue, and game-time weather.

Resource	Endpoint	Grain
leagues	GET /v1/leagues	one row per supported league
teams	GET /v1/teams	one row per canonical team
players	GET /v1/players	one row per canonical player
games	GET /v1/games, GET /v1/games/{game_id}	one row per game

All four need an API key, return application/json, and (except /v1/leagues, which always fits one page) paginate with the {data, next_cursor} envelope described in Pagination. List endpoints reject query parameters they don’t know, so a typo is a 400, not a silent full scan.

Fetching

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

betflux games --league NBA --date-from 2026-05-01 --date-to 2026-05-07
betflux teams --league NBA

with Client() as bf:
    teams = bf.teams(league="NBA")
    games = bf.games(league="NBA", date_from="2026-05-01", date_to="2026-05-07")

The SDK methods return complete lists of plain dicts (pagination is handled for you); the CLI renders a table by default and --format json|jsonl|csv for the full record.

Current state, not history

Reference data is current state, refreshed a few times an hour. A game’s score and status move while it is live and settle when it completes; a postponed game shows its new start and the reason; a traded player’s current_team_id changes. Earlier values are not kept here. For the history of a game’s state over time, use the game-state-timeline dataset; for the history of its odds, sportsbook-lines.

Identity

• Game ids are readable — LEAGUE_AWAY_HOME_YYYYMMDD, ET date, _2 for the second game of a doubleheader — and case-insensitive. See Core concepts.
• Team and player ids are UUIDs, stable across seasons. They are the values the datasets’ home_team_id, away_team_id, and *_player_ids columns carry, so a join from a dataset to the reference data never goes through a name.
• Venues have no endpoint of their own: a game carries its venue’s venue_id and descriptive fields inline.