Skip to content
Product Documentation

List a live game's line segments (manifest + position cursor).

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

Until a game settles, its sportsbook-lines data is published as an append-only series of Parquet segments plus a current board (adr-0037). This route returns the manifest with a URL per segment; every segment URL carries ?rows= (the listed row count) — fetch listed URLs verbatim. The final artifact replaces all of it the moment it lands: once rows.parquet exists this route answers 404 with reason: "final_available" and the dataset route’s URL under final.

Pass cursor from the previous response to get only what is new: segments above the cursor’s seq, plus the cursor’s own segment when it has grown, carrying from_row so you read rows [from_row, rows). Fully-consumed segments are omitted, the response cursor echoes the request when nothing is new, and it is "0:0" while no segment exists yet.

A cursor must name a position the log still holds: 0:0, or a segment seq with at least rows rows. Anything else means the live log was rebuilt since the cursor was minted (a version bump, lost state) and answers 409 live-cursor-reset — list again without a cursor. A cursor this route returned never 409s while the log stands.

The cursor is a position, not a timestamp, on purpose: a slower operator’s file lands after a faster one’s later-stamped rows, so a later segment can end earlier than the one before it and a timestamp would silently drop rows.

Live rows are provisional — the final build may revise them. Cached 5 s at the edge; no rows are debited for the listing itself.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
game_id
required

Public game id (e.g. NBA_GSW_MIA_20250408, case-insensitive).

string

Public game id (e.g. NBA_GSW_MIA_20250408, case-insensitive).

Query Parameters

Section titled “Query Parameters”
cursor

Opaque position cursor from a previous /segments response.

string
/^\d+:\d+$/

Opaque position cursor from a previous /segments response.

Responses

Section titled “Responses”

200

Section titled “200”

The live manifest, with a URL per segment and per board file, and the cursor to pass next time.

Media typeapplication/json
object
game_id
required
string
dataset
required
string
Allowed values: sportsbook-lines
schema_version
required
string
provisional
required
boolean
updated_at
required
string
applied_through
required
string | null
operators
required
object
key
additional properties
object
last_row_at
required
string
observed_through
required
string | null
segments
required
Array<object>
object
seq
required
integer
rows
required
integer
closed
required
boolean
min_timestamp
required
string
max_timestamp
required
string
url
required

/v1/games/{game_id}/sportsbook-lines/segments/{seq}?rows={rows} — fetch it verbatim; the rows it carries is this entry’s rows.

string
from_row

Rows of this segment the cursor already consumed; read rows [from_row, rows).

integer
board
required
object
rows
required
integer
files
required
Array<object>
object
operator
required
string
rows
required
integer
url
required
string
cursor
required

Position of everything listed; the request cursor echoed when nothing is new; “0:0” when no segment exists yet.

string
Example
{
  "dataset": "sportsbook-lines"
}

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 has no entitled tier — subscription lapsed or absent (problem type subscription-required; the body carries an 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), or the requested range exceeds the tier’s history window (history-restricted).

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, a league outside the dataset’s coverage, or no live artifacts for the game. reason is final_available when the game has settled (fetch final, the dataset route) and no_live_artifact when it has not started being tracked.

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 cursor names a position the live log no longer holds — the log was rebuilt since the cursor was minted (problem type live-cursor-reset, with game_id). List again without a cursor. Never cached; nothing debited.

Media typeapplication/problem+json
object
type
required
string
Allowed values: https://api.betflux.ai/problems/live-cursor-reset
title
required
string
status
required
number
Allowed values: 409
detail
required
string
game_id
required
string
Example
{
  "type": "https://api.betflux.ai/problems/live-cursor-reset",
  "status": 409
}

429

Section titled “429”

Rate limit, monthly row quota, or ops throttle — the problem type distinguishes rate-limited, quota-exhausted, and throttled.

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