Skip to content
Product Documentation

Download a dataset's per-game Parquet artifact.

GET
/v1/games/{game_id}/{dataset}
curl --request GET \
  --url https://api.betflux.ai/v1/games/example/closing-lines \
  --header 'Authorization: Bearer <token>' \
  --header 'Range: bytes=0-65535'

Streams the game’s Parquet file (application/vnd.apache.parquet) for the named dataset. The server serves bytes only — query the file locally with DuckDB or pyarrow; filtering happens client-side.

Datasets: closing-lines, game-state-timeline, market-results, sportsbook-lines (discover via /v1/datasets). Per-dataset row schemas are published as the OpenAPI components ClosingLinesRow, GameStateTimelineRow, MarketResultsRow, SportsbookLinesRow and served by /v1/datasets/{name}/schema.

game_id is the game id (e.g. NBA_GSW_MIA_20250408, case-insensitive) — discover ids via /v1/games. A trial key (the free sample) reads only games dated the first Saturday of a month or the Sunday after it, by the date in the id; any other date is 403 history-restricted with upgrade_url and sample: "first-weekend", answered before the cache or the file is touched.

HTTP Range requests are honored (206 with Content-Range; partial responses are never cached). Metering: a successful read counts the game once per billing period, whatever the dataset, byte range or cache state, and every later read of a counted game is free. On a capped plan the response reports what it cost: X-Betflux-Game (new, already or exempt) and X-Betflux-Games-Remaining.

Live games: sportsbook-lines is also served before it settles. When the final artifact does not exist yet but the game is being served live, the 404 carries problem type not-final with the game’s /sportsbook-lines/segments and /sportsbook-lines/board URLs. The final artifact wins the moment it exists.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
game_id
required

Game id (e.g. NBA_GSW_MIA_20250408, case-insensitive).

string

Game id (e.g. NBA_GSW_MIA_20250408, case-insensitive).

dataset
required

Dataset name from /v1/datasets.

string
Allowed values: closing-lines game-state-timeline market-results sportsbook-lines

Dataset name from /v1/datasets.

Header Parameters

Section titled “Header Parameters”
Range

Standard HTTP byte range, e.g. bytes=0-65535. Satisfiable ranges return 206.

string
Example
bytes=0-65535

Standard HTTP byte range, e.g. bytes=0-65535. Satisfiable ranges return 206.

Responses

Section titled “Responses”

200

Section titled “200”

The complete Parquet artifact. ETag is the artifact’s content hash; Accept-Ranges: bytes; X-Betflux-Rowcount is the artifact’s row count; X-Betflux-Dataset-Version is the version the game’s file was built at — games in one pull can differ within a compatibility line (see versions on /v1/datasets; the file’s dataset_version column says the same).

Media typeapplication/vnd.apache.parquet
string format: binary

206

Section titled “206”

The requested byte range of the artifact (Content-Range set). Never served from the edge cache.

Media typeapplication/vnd.apache.parquet
string format: binary

400

Section titled “400”

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

Media typeapplication/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
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

401

Section titled “401”

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

Media typeapplication/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
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

402

Section titled “402”

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

Media typeapplication/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
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

403

Section titled “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".

Media typeapplication/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
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

404

Section titled “404”

Unknown dataset name (‘Unknown dataset’), a sports dataset (reason msf_dataset, with its snapshot route), unresolvable game id (‘Game not found’), a league outside the dataset’s coverage, a resolved game with no artifact (‘No for this game’; artifacts appear shortly after a game settles), or a game still being served live (problem type not-final, with game_id and the live.segments / live.board URLs).

Media typeapplication/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
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}

429

Section titled “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.

Media typeapplication/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
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example"
}