Skip to content
Product Documentation

Download one live segment's Parquet.

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

The segment’s bytes, in exactly the columns the final artifact publishes — concatenating every segment in seq order reproduces the game’s line history so far.

Closed segments are immutable and cached 24 h; the highest seq is the open tail, rewritten in place as rows are appended and cached 5 s. The live engine guarantees prefix stability: an object at a given seq only ever grows and its first rows never change, so a (seq, rows) pair always names the same rows.

rows — carried by every URL /segments lists — is the row count the listing promised. When the object holds fewer, the log was rebuilt underneath the listing and the response is 409 live-segment-behind (never cached, nothing counted): list the segments again. The edge cache key includes rows, so each (seq, rows) is its own entry and a cached body always held at least rows rows. Without rows the object is served as is (hand-built URLs, DuckDB).

HTTP Range is honored (206; partial responses are never cached; rows is still checked).

Metering: a segment read counts its game once per billing period, like any other read of the game, so every later segment, re-read, poll of the open tail and Range request of that game is free.

Live lines are a plan feature (limits.live on /v1/me). On a plan without them this route answers 403 plan-excludes — with feature: "live", required_tiers and upgrade_url — before any cache, file or usage is touched; the settled game’s final artifact on the dataset route is open to every plan.

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).

seq
required

Segment sequence number as listed by /segments (a non-negative integer).

string

Segment sequence number as listed by /segments (a non-negative integer).

Query Parameters

Section titled “Query Parameters”
rows

Row count the listing promised for this segment (listed segment URLs carry it — use them verbatim). 409 live-segment-behind when the object holds fewer rows than this.

string
/^\d+$/

Row count the listing promised for this segment (listed segment URLs carry it — use them verbatim). 409 live-segment-behind when the object holds fewer rows than this.

Header Parameters

Section titled “Header Parameters”
Range

Standard HTTP byte range, e.g. bytes=0-65535.

string
Example
bytes=0-65535

Standard HTTP byte range, e.g. bytes=0-65535.

Responses

Section titled “Responses”

200

Section titled “200”

The segment’s Parquet. X-Betflux-Rowcount is its row count. Accept-Ranges: bytes.

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

206

Section titled “206”

The requested byte range of the segment (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”

Unresolvable game id, no live artifacts for the game, or no segment with that sequence number.

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"
}

409

Section titled “409”

The object holds fewer rows than rows promised (problem type live-segment-behind, with game_id, seq and the requested rows). List the segments again. Never cached; nothing counted.

Media typeapplication/problem+json
object
type
required
string
Allowed values: https://api.betflux.ai/problems/live-segment-behind
title
required
string
status
required
number
Allowed values: 409
detail
required
string
game_id
required
string
seq
required
integer
rows
required

The rows the request asked for — what the listing promised.

integer
Example
{
  "type": "https://api.betflux.ai/problems/live-segment-behind",
  "status": 409
}

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"
}