Skip to content

Data model

One model for every product. An event (a game or a competition) has participants and markets; a market has selections, each with a price. Scores add the scoresheet, and grading the grading (our verdicts); both hang off the event's id.

Every field is always present: null when it is unknown or does not apply. The one exception is an event's markets, which comes only with an event fetched with its markets or sent in a snapshot.

Event

A game, a match or a competition. Pre-game example, live example.

Field Type What it is
id string evt_…. The same game has the same id in every product
product string The product this copy of the event belongs to
sport {id, name} Sport, from /v1/catalog/sports
league {id, name, country} League or competition. id is lg_…; country is ISO 3166-1 alpha-2, or null
name string Display name: "Home vs Away" for a game; the competition's name for futures
participants list of Participant The teams or competitors. Empty for futures, whose competitors are in the selections
startAt time or null Scheduled start; null when there is none (some futures)
status string See Event status
score Score or null The live score (live and the scores board)
clock Clock or null The game clock (live and the scores board)
updatedAt time When the event's own fields last changed. A change of its markets does not move it
rotation Rotation or null The game's rotation numbers. See Rotation numbers
schedule Schedule or null The first and the current start time. See Schedule
details object or null The race's details in horse racing; null in every other product
markets list of Market Only on an event fetched with its markets, or in a snapshot message

Participant

Field Type What it is
id string par_…
name string Display name
role string home or away; runner in horse racing. Other values are reserved: ignore a participant whose role you do not know
number string or null A runner's number in horse racing; null otherwise
details object or null A runner's details in horse racing; null otherwise

home and away are the teams' real roles in the game, in every product.

Score and Clock

score is {home, away, periods}, where periods lists {period, home, away} with period ids from /v1/catalog/periods (1h, q3, p2, set1, i7…). In set sports, home and away count sets.

clock is {period, seconds, running}: the current period id, the seconds elapsed in it, and whether the clock is running. Any of them is null when the sport or the game does not give it.

Event status

Status Meaning
scheduled Not started
live In play
interrupted Stopped during play; it may resume
finished Over
postponed Moved to a later date
cancelled Will not be played
abandoned Stopped and will not resume

How a game ended, for settlement, is in its scoresheet.

Market

Something to bet on in an event. One market holds one line: alternate lines are markets of their own.

Field Type What it is
id string mkt_…
eventId string The event it belongs to
type string Market type, from /v1/catalog/market-types. Its form says how to read the selections
name string Display name, in English: "Total – 1st Half", "Patrick Mahomes Passing Yards"
period string Period id, from /v1/catalog/periods
line number or null The market's line. See Lines
participant {id, name, number} or null The team or player the market is about (a team total, a player prop)
main boolean false on alternate lines
book {id, name} or null The sportsbook whose line this is; null on our own lines. See Sportsbooks
status string open, suspended or closed. See Status
selections list of Selection Its outcomes
updatedAt time When the market last changed
legs, raceEventIds integer and list of strings, or null A pool's runners per bet and its races in horse racing; null otherwise

Selection

One outcome of a market.

Field Type What it is
id string sel_…
name string Display name, in English: "Boston Celtics -4.5", "Over 2.5", "Yes"
side string What the selection backs. See Sides
participant {id, name, number} or null The team, player or competitor it backs, when it backs one
line number or null Its own line: the handicap of its side, the total, a player's figure
range {min, max} or null A band (player_band form): the figure must fall in it
price Price or null null when no price is available
status string open, suspended or closed
opening {line, price, at} or null On a book's pre-game market: the first line and price the book posted. null on our own lines, on a book's in-play market, and when the book's opening is not known
leg, couplingGroup integer and string, or null A runner's race in a multi-race pool and its coupled entry in horse racing; null otherwise

Sides

Side Backs
home, away, draw That result, or that team (handicaps, team-first markets)
home_or_draw, draw_or_away, home_or_away Double chance
over, under The total or the player's figure against line
yes, no A yes/no proposition
odd, even Odd/even
exact An exact figure, in line
range A band, in range
participant The selection's participant: a player, or a futures competitor
other Read the selection's name: a correct score, a half-time/full-time pair, a margin, "No Goalscorer"…

How each market form uses them is in the catalogs.

Price

{"decimal": 1.909, "american": -110}

Both figures, always together and always consistent: decimal has at most three decimals and american is the integer it converts to. decimal includes the stake: a winning 10 at 1.909 returns 19.09.

price is null when there is no price. A selection without a price is never open.

Market and selection status

Status Meaning
open Can be bet now
suspended Cannot be bet right now. The last price is kept so you can show it, greyed out. It comes back as open when betting resumes
closed Final. It will not reopen

A suspended market is never dropped for being suspended. While the product's feed.status is degraded, treat every open market of the product as suspended (see Connecting).

Ids

Ids are opaque, stable strings: evt_…, mkt_…, sel_…, par_…, lg_…, bk_…. Store them and join on them; never parse them.

  • A game keeps its evt_ in every product: pregame, props, live, scores and grading, and from before the start to after the end.
  • A market or a selection keeps its id while it exists, whatever happens to its price, status or name.
  • Our own lines are one market per line. When our line moves (a spread from -4.5 to -5), the market at the old line goes (market.remove) and a market at the new line comes (market.upsert), with new mkt_ and sel_ ids. A book's main market is the exception: it keeps its id while its line moves (see Sportsbooks).
  • A market id is unique within a product. The same game's market can carry the same mkt_ in live and before the game: key your markets by product and id.
  • A selection id never names two different bets.
  • par_ ids are per sport and name: a team's par_ is the same in all its games. A player's par_ is the same in his markets and in a scoresheet's timeline, boxscore and lineups when they spell his name the same way (some names are spelled differently: check the name too). A futures competitor has a par_ of its own, which is not the one the same team has in its games.

Times

Every time the API sends is ISO 8601 in UTC with milliseconds: 2026-11-14T20:00:00.000Z. The filters that take a time also accept other ISO 8601 forms with their zone, and a date alone (see Filters).

Lines

Lines are numbers.

  • Handicaps: the market's line is the home team's handicap, and each selection carries its own: home -4.5, away +4.5. A 0 handicap is a pick'em.
  • Totals: the market's line is the total; both selections carry it.
  • Quarter lines (-0.25, 2.75) split the stake in two halves on the lines either side (see Grading rules).
  • Player props: the market's line is the player's figure.
  • One market, one line. The main line has main: true; each alternate line is another market of the same type and period, with main: false.

Sportsbooks

Besides our own lines (book: null), pregame and live carry the lines of the sportsbooks, such as bet365, DraftKings or Pinnacle, each market with its book:

{"book": {"id": "bk_kqlifwyx2m3ast3f", "name": "DraftKings"}}

One game carries the same type and period from many books, each its own market, next to ours. The books whose lines your products carry now are at /v1/catalog/books.

What a book's market is

  • Types: a game's moneyline (moneyline, or match_result when the game has a draw), its spread (spread, with the book's alternate spreads as markets with main: false), its total (total) and each team's total (team_total, with the team as participant). All of them are main lines, so a book's markets are in pregame before the game and in live once it is under way, never in props.
  • Periods: the whole game in every sport. The moneyline, the main spread and the total also come for the halves and quarters in basketball and American football, the halves in soccer and the periods in ice hockey; team totals and alternate spreads are for the whole game only.
  • Sides: home and away are the teams' roles in our event, as in our own lines; a handicap's market line is the home team's.

How it changes

  • A book's main market keeps its id while its line moves. It is "this book's spread for this game": its line and prices change in place, so its history is one market. This is the one difference from our own lines, which are one market per line.
  • Alternate spreads (main: false) are markets of their own, one per line, as ours: when a book moves its alternate spread, the market at the old line goes (market.remove) and one at the new line comes.
  • updatedAt is when the book last posted a line of the market.
  • Opening line. opening, on each selection of a book's pre-game market, is the first line and price the book posted for it: {"line", "price", "at"}; null when it is not known. The current ones are line and price.
  • Closing line. A book's pregame market is closed when the game starts, with its last line and price: the closing line. Its updatedAt is then the start. A closed market stays closed, also if the start later moves. It goes when the game leaves the pregame board, so keep the closing line from the stream's market.upsert that closes it: REST may no longer have it soon after the start.
  • When the books' lines are interrupted, every book's market is suspended, with its last prices, until they come again; it then comes back open with a market.upsert, as any other. Only the books' markets: our own lines and the product's feed.status are not affected.
  • If the books' lines stop altogether for about ten minutes, the books' markets are removed (market.remove), and so are the games only the books list (event.remove). When the lines return, so do they, with the same ids.
  • Not graded. The grading add-on gives no verdict on a book's market: it never appears in a grading's markets or held, and does not count for complete.
  • A selection without a price is suspended, as in our own lines. A market can be open while some of its selections are suspended: check each selection's status.
  • In play, live carries the books' lines of the games under way, from the start until the game is over: markets of their own, with their own ids and opening: null, holding only the lines each book posted since the start. Their prices are updated every few seconds.
  • In play, after an interruption, a game's book markets stay suspended until a new line of that game comes: a price that may have missed a change is never reopened as it was. A game whose lines do not move stays suspended until it leaves live.

Games only the books list are events of their own in pregame and, once under way, in live, with the books' rotation numbers (official: true) and the same model as any other game. They carry only the books' lines: in play no score or clock, no scoresheet in scores and no verdicts in grading. They leave live with an event.remove when the game is over, without a finished status.

  • If the game later comes in our own lines too, it keeps its evt_ and our markets join the books'; from then on it is a game like any other.
  • In the rare case the two cannot be matched for sure in time (the sides listed the other way round, for example), the first event is removed (event.remove) and the game goes on under another evt_; ids are never reused.
  • Postponed or cancelled, such a game is removed (event.remove): it does not come with a postponed or cancelled status.
  • A game whose competition we cannot name for sure is under its sport's generic league, such as Soccer.

REST and the stream have no filter by book: they send every book's markets with ours. To show only our lines, keep the markets with book: null; to show one book, keep those with its book.id; to compare books, group by type, period, participant and main.

Rotation numbers

rotation is a game's rotation numbers, as sportsbooks print them on the board and on the ticket:

{"away": 501, "home": 502, "draw": null, "official": true, "added": false}

Games with a home and an away side usually have one, in live, pregame, props and the scores board; it is null while a game has no numbers yet, and elsewhere.

  • draw is the draw's number, in games with a three-way result.
  • official: true: the official numbers the sportsbooks use. false: provisional, or ours while there are no official ones (ours run from 5 000 000 up, apart from the official ones). They may change: a provisional number gets its definitive one, and ours give way to the official ones when there are some.
  • added: true: a game the books added outside the main schedule; its numbers are the books' own.
  • Numbers are not ids. They are reused across days, and a game keeps its evt_ when its numbers change. Join on evt_; show the numbers.
  • A game's periods and props share its numbers: the market says the period.

Schedule

schedule is {originalStartAt, startAt, timeConfirmed} in live, pregame, props, futures and the scores board:

  • originalStartAt: the first start time we published for the game. It never changes.
  • startAt: the current one, the same as the event's startAt.
  • timeConfirmed: false while the hour is still to be announced (the date is known); null when it is not known.

A start that moves, and a postponement (status: postponed), comes as an event.upsert. What a changed start means for bets already taken is your rule to apply. A start that moves, and the official rotation numbers, can take up to 10 minutes to show.

One game, everything about it

Everything about a game hangs off its evt_:

  • the whole game, halves, quarters, periods, innings and sets are markets of the same event, told apart by period;
  • team markets and player props are markets of the same event; the team or player is the market's participant;
  • before the start, its main lines are in pregame and the rest in props; in play, everything is in live; afterwards its scoresheet is in scores and our verdicts in grading.

GET /v1/events/{eventId} (example) answers, for the products of your key:

Field What it is
event The event, without markets, from the product where it is most current. null once the game has left every board and only its scoresheet or verdicts are kept
products One entry per product that offers the game now: {product, status, markets, updatedAt, href}, where markets is how many it has there and href the event with its markets
scoresheet The link to its scoresheet, once there is one and your key includes scores; otherwise null
grading One {product, href} per product of lines your key includes that has verdicts on the game, when your key includes grading
result The link to the race's result in horse racing, once there is one; null otherwise

The links are paths: prefix them with https://api.lineval.com.

Every market type belongs to a group, for building tabs: game, team, stats, player and futures (Market groups). To fetch one tab, add groups to the event call or to the stream, for example ?groups=player.

Scoresheet and Grading

The scoresheet (how a game ended: score, periods, statistics, timeline, boxscore, lineups, and how sure we are) is described in Scores. The grading (our verdict on each selection) is described in Grading.