List games with league, ET date-range, team, and status filters.

GET

/v1/games

const url = 'https://api.betflux.ai/v1/games?league=MLB&status=SCHEDULED';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.betflux.ai/v1/games?league=MLB&status=SCHEDULED' \
  --header 'Authorization: Bearer <token>'

Authorizations

bearerAuth

Parameters

Query Parameters

league

string

Allowed values: MLB NBA NHL NFL NCAAM NCAAF

date_from

Inclusive ET game date (YYYY-MM-DD); pair with date_to.

string

Inclusive ET game date (YYYY-MM-DD); pair with date_to.

date_to

string

team

Canonical team name; matches home or away.

string

Canonical team name; matches home or away.

status

string

Allowed values: SCHEDULED DELAYED STARTED SUSPENDED COMPLETED POSTPONED

limit

integer

>= 1 <= 10000

cursor

string

Responses

200

A page of games.

application/json

object

data

required

Array<object>

object

required

Game id (e.g. NBA_GSW_MIA_20250408).

string

league

required

League code, e.g. NBA, NFL, MLB, NHL, NCAAM, NCAAF.

string

game_date

required

Eastern-Time calendar date of the scheduled start (matches closing-lines game_date).

string

start_time

required

Scheduled start, ISO 8601 UTC.

string

status

required

Schedule status, e.g. SCHEDULED, STARTED, COMPLETED.

string

Allowed values: SCHEDULED DELAYED STARTED SUSPENDED COMPLETED POSTPONED

is_live

required

True while the game is in progress.

boolean

home_team

required

Canonical home team name.

string

home_team_abbr

required

Home team abbreviation, e.g. MIA.

string

home_team_id

required

Canonical home team UUID (matches /v1/teams ids).

string

away_team

required

Canonical away team name.

string

away_team_abbr

required

Away team abbreviation, e.g. GSW.

string

away_team_id

required

Canonical away team UUID (matches /v1/teams ids).

string

season

required

Season slug the game belongs to, e.g. 2026-regular.

string | null

season_type

required

PRESEASON, SEASON (regular) or POSTSEASON.

string | null

end_time

required

Observed end, ISO 8601 UTC; null until known (often never set).

string | null

week

required

Schedule week (NFL, NCAAF); null for other leagues.

integer | null

is_neutral_venue

required

True when neither team is the venue’s home side.

boolean

delayed_or_postponed_reason

required

Reason while status is DELAYED or POSTPONED; null otherwise.

string | null

broadcasters

required

Broadcast outlets; empty when unknown.

Array<string>

attendance

required

Reported attendance; null until posted.

integer | null

home_score

required

Home score so far; final once status is COMPLETED. Null before tip-off.

integer | null

away_score

required

Away score so far; final once status is COMPLETED. Null before tip-off.

integer | null

current_period

required

Quarter / inning / period / half in progress; null before the game and after it ends.

integer | null

current_period_seconds_remaining

required

Clock seconds left in the current period (timed sports); null otherwise.

integer | null

current_period_half

required

TOP or BOTTOM of the current inning (MLB); null elsewhere.

string | null

current_intermission

required

Label for a break in play (e.g. HALFTIME); null while play is on.

string | null

period_scores_home

required

Home line score, one entry per completed or in-progress period.

Array<integer>

period_scores_away

required

Away line score, index-aligned with period_scores_home.

Array<integer>

venue_id

required

Venue UUID; null when no venue is known.

string | null

venue_name

required

Venue name, e.g. Truist Park.

string | null

venue_city

required

Venue city with its region, e.g. Atlanta, GA.

string | null

venue_country

required

Venue country, e.g. USA.

string | null

venue_latitude

required

Venue latitude (WGS84).

number | null

venue_longitude

required

Venue longitude (WGS84).

number | null

venue_capacity

required

Largest sports capacity of the building.

integer | null

venue_surface

required

Playing surface, e.g. Kentucky Bluegrass, FieldTurf; null when unknown.

string | null

venue_has_roof

required

True for covered venues (domes and arenas).

boolean | null

venue_has_retractable_roof

required

True when the roof can open.

boolean | null

weather_type

required

Weather category at game time, e.g. SUNNY, CLOUDY, LIGHT_RAIN; null indoors or when unavailable.

string | null

weather_description

required

Free-text weather description, e.g. sky is clear.

string | null

weather_temperature_f

required

Temperature in °F.

number | null

weather_wind_speed_mph

required

Wind speed in mph.

number | null

weather_wind_direction_degrees

required

Wind origin bearing in degrees.

integer | null

weather_wind_direction_label

required

Compass label for the wind origin, e.g. WSW.

string | null

weather_precipitation_type

required

RAIN, SNOW, … when precipitation is forecast; null otherwise.

string | null

weather_precipitation_percent

required

Precipitation probability in percent.

integer | null

weather_humidity_percent

required

Relative humidity in percent.

integer | null

next_cursor

required

string | null

Example

{
  "data": [
    {
      "status": "SCHEDULED"
    }
  ]
}

400

Validation failed — unknown or invalid query parameter, or a malformed range (problem type validation-error).

application/problem+json

RFC 9457 problem details. Dispatch on the stable type URI (https://api.betflux.ai/problems/*), never on the English title.

object

type

required

Stable problem type URI.

string

title

required

Short human-readable summary.

string

status

required

HTTP status code.

integer

detail

Explanation specific to this occurrence.

string

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

401

Missing, malformed, or unrecognized API key (problem type invalid-key).

application/problem+json

RFC 9457 problem details. Dispatch on the stable type URI (https://api.betflux.ai/problems/*), never on the English title.

object

type

required

Stable problem type URI.

string

title

required

Short human-readable summary.

string

status

required

HTTP status code.

integer

detail

Explanation specific to this occurrence.

string

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

402

The key is valid, but the account has no active subscription (problem type subscription-required). The response includes upgrade_url.

application/problem+json

RFC 9457 problem details. Dispatch on the stable type URI (https://api.betflux.ai/problems/*), never on the English title.

object

type

required

Stable problem type URI.

string

title

required

Short human-readable summary.

string

status

required

HTTP status code.

integer

detail

Explanation specific to this occurrence.

string

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

403

API key revoked or suspended (problem type key-disabled); a feature the plan does not include (problem type plan-excludes, with feature — live for the live sportsbook-lines routes, league_datasets for league-scoped datasets — required_tiers and upgrade_url; never worth retrying on the same key); or a game outside the key’s history window (problem type history-restricted): a trial key reads only games dated the first Saturday of a month or the Sunday after it, and its 403 carries upgrade_url and sample: "first-weekend".

application/problem+json

RFC 9457 problem details. Dispatch on the stable type URI (https://api.betflux.ai/problems/*), never on the English title.

object

type

required

Stable problem type URI.

string

title

required

Short human-readable summary.

string

status

required

HTTP status code.

integer

detail

Explanation specific to this occurrence.

string

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

429

Rate limit, games allowance, or ops throttle — the problem type distinguishes rate-limited, quota-exhausted and throttled. quota-exhausted refuses only a new game past the period’s allowance (games already counted stay readable) and carries reset_at, upgrade_url, game_id, games_used and games_allowance.

application/problem+json

RFC 9457 problem details. Dispatch on the stable type URI (https://api.betflux.ai/problems/*), never on the English title.

object

type

required

Stable problem type URI.

string

title

required

Short human-readable summary.

string

status

required

HTTP status code.

integer

detail

Explanation specific to this occurrence.

string

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

List games with league, ET date-range, team, and status filters.

Authorizations

Parameters

Query Parameters

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

402

Examplegenerated

403

Examplegenerated

429

Examplegenerated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated