Skip to content

Connecting and resuming

There are two ways in, and most integrations use both:

  • REST to fetch: a page of events, one event with its markets, a scoresheet, a grading, the catalogs. Good for a first load, for back-filling and for occasional checks.
  • The stream to follow: one WebSocket that sends a snapshot of each product you ask for and then every change, in order, as it happens. It is the only way to keep prices current.

REST

Call Returns
GET /v1/{product}/events Events without markets, sorted by startAt. Filters: sports, leagues (comma-separated ids), from, to (on startAt), updatedSince (on the event's updatedAt). Paginated
GET /v1/{product}/events/{eventId} One event with all its markets. Narrow with periods, marketTypes, groups (comma-separated)
GET /v1/events/{eventId} One game across the products of your key: where it is offered, and where its scoresheet and verdicts are
GET /v1/scores Scoresheets, sorted by updatedAt. Filters: sports, leagues, updatedSince, confidence=confirmed. Paginated
GET /v1/scores/{eventId} The latest scoresheet of one game. With confidence=confirmed, 404 while the latest is not confirmed
GET /v1/{product}/grading Our verdicts on live, pregame or props, sorted by updatedAt. Filters: sports, leagues, updatedSince. Paginated
GET /v1/{product}/grading/{eventId} Our latest verdicts on one game in live, pregame or props
GET /v1/catalog/{name} sports, periods, market-types, market-groups, stat-keys, leagues or books
GET /v1/health Whether the API is serving: 200 with {"status": "ok"}, or 503 with {"status": "starting"}. No key needed; with your key it also lists, under products, each product of your key with ready, status (ok or degraded, as in feed.status) and events (how many it holds now)

{product} is the product's id: pregame, live, props, futures or scores (the live board of scores).

Filters

  • Every filter is a comma-separated list. sports and leagues take ids from the catalogs; an id with no events gives an empty page. sport and league are accepted too, for compatibility (given both, they add up).
  • periods, marketTypes and groups take ids from the catalogs too, and are checked: an unknown value is a 400 bad_request, never an empty answer, so a typo cannot pass for "no markets".
  • from, to and updatedSince take an ISO 8601 date and time with its zone: 2026-11-21T18:00:00Z, 2026-11-21T18:00:00.000Z or 2026-11-21T13:00-05:00 (encode + as %2B). A date alone, 2026-11-21, is its midnight UTC. from and to include the time they name: for the whole of 21 November, from=2026-11-21&to=2026-11-21T23:59:59.999Z. Anything else, a time without its zone included, is a 400 bad_request that names the parameter.
  • updatedSince on events looks at the event's own fields (its status, score, start time…), not at its markets. To follow prices, use the stream.

Pagination

Lists answer {"data": [...], "nextCursor": "..."}. Pass nextCursor back as cursor, with the same filters, until it is null. The cursor is opaque: do not build or change one. limit sets the page size: 100 by default, at most 500; a larger value is served as 500.

Caching and compression

  • ETag. Every 200 of the data and catalog routes carries one, weak (W/"…"): events, pages, a game's family, scoresheets, gradings and catalogs. Send it back as If-None-Match and, while nothing changed, you get 304 Not Modified with no body. A 304 still counts as a request against your limit.
  • gzip. Send Accept-Encoding: gzip and every data and catalog response of 1 KB or more comes compressed; smaller ones are sent as they are.
  • Catalogs that need no key can be cached for five minutes (Cache-Control: public, max-age=300).

The stream

wss://api.lineval.com/v1/stream?products=live,pregame

products is required: one or more of the products of your key, comma-separated. Optional filters, each a comma-separated list:

Parameter Applies to Values
sports, leagues, events every product catalog ids, event ids (sport, league accepted too)
marketTypes, periods, groups products with markets catalog ids; unknown ids close the stream with 4400
confidence scores confirmed: only scoresheets whose confidence is confirmed; a withdrawal still comes as scoresheet.withdrawn
gradingProducts grading live, pregame, props: by default, every one your key includes
since every product where to resume, per product: live:1795286732015467,pregame:1795286711002144

A request the stream cannot serve is refused with a close code before any message:

  • 4400: products missing, an unknown or unavailable product, an unknown id in marketTypes, periods, groups or gradingProducts, a confidence other than confirmed, or a malformed since;
  • 4401: no key, or a key that is not valid;
  • 4403: a product your key does not include; grading with a key that has no product of lines (live, pregame, props); or a gradingProducts value your key does not include.

Messages

Every message has the same envelope:

{"type": "market.remove", "seq": 1795286733270154, "ts": "2026-11-21T18:45:33.270Z", "product": "live", "data": {"eventId": "evt_kdmaf647wxusthff", "marketId": "mkt_4ivtdkeuy6gd24da"}}
Field What it is
type What the message is, below
seq A point in its product's sequence, the same on every server and across our restarts. See How seq goes. null on a heartbeat
ts When it was sent
product The product it belongs to. null on a heartbeat
data The payload
Type data What to do
snapshot.begin {} A full snapshot of the product follows
snapshot an event with all its markets Store it, replacing what you had for that event
snapshot.end {"since": seq} The snapshot is complete. Deltas follow
event.upsert an event, without markets Add the event, or replace its fields. Its markets stay as they are
event.remove {"eventId"} Drop the event and all its markets
market.upsert a whole market Add the market, or replace it whole. Never merge fields
market.remove {"eventId", "marketId"} Drop the market
scoresheet a game's whole scoresheet Replace the one you had for that game (scores)
scoresheet.withdrawn {"eventId", "revision", "confidence", "updatedAt"} A confirmed scoresheet is no longer confirmed (now provisional or disputed): check anything you settled on it (scores; see Scores)
grading our whole verdicts on one product of lines of one game Replace what you had for that game and product (grading)
feed.status {"state": "ok" \| "degraded"} degraded: the data may be stale. Treat every open market of the product as suspended until ok
heartbeat {} Sent every 15 s when nothing else is. Not part of any product's sequence

A session, message by message, is in stream-session.json: a reconnect with products=scores,live,grading&since=live:…,grading:…, where scores starts with a snapshot and live and grading resume where they were.

Every upsert is whole. A market.upsert carries the entire market with every selection; an event.upsert carries every field of the event (without markets). Replace, never patch.

Each product is a separate board. The same game can be on your pregame, props and live boards at once, with the same evt_, and a market can have the same mkt_ in live and before the game. Keep one store per product, keyed by id: an event.remove in live does not remove the game from scores.

feed.status is sent once per product right after its snapshot (or after the missed messages of a resume), and again whenever it changes. It is an overlay on the whole product: while degraded, show prices greyed out and accept no bets on them. When it returns to ok, the product is back in sync and each market's own status applies.

Snapshots and deltas

On connect, each product you list sends snapshot.begin, one snapshot per event (filtered by your filters), snapshot.end and its feed.status; then only changes. In scores, each event of the snapshot is followed by its scoresheet when the game has one. The snapshot of grading holds no games: catch up with GET /v1/{product}/grading?updatedSince=… after it (see Grading).

How seq goes

  • After a snapshot, each event.*, market.*, scoresheet, scoresheet.withdrawn and grading message has a higher seq than the one before.
  • snapshot.begin, snapshot.end and feed.status are not changes: they carry the seq of the point they mark, which the message before may share.
  • Inside a snapshot, each event and its scoresheet carry their own seq, never higher than the snapshot's since, in no order: they are not a place to resume from. Resume from snapshot.end on.
  • A reconnect that cannot resume gets a fresh snapshot, whose seq may be lower than your since.

So never drop a message because its seq is not higher than the last one: seq says where to resume, not what is new.

Resuming with since

Keep, per product, the since of its snapshot.end and then the seq of every message you apply after it:

if kind == "snapshot.begin":
    in_snapshot.add(product)
    since.pop(product, None)
elif kind == "snapshot.end":
    in_snapshot.discard(product)
    since[product] = msg["data"]["since"]
elif msg["seq"] is not None and product not in in_snapshot:
    since[product] = msg["seq"]

When you reconnect, pass every product's position:

/v1/stream?products=live,pregame&since=live:1795286732015467,pregame:1795286711002144
  • If the server still holds what you missed, you get exactly those messages, in order, and no snapshot.
  • If not, you get a fresh snapshot of that product. Replace its board with it: the events and markets you hold for that product. Keep the scoresheets and gradings you hold, and catch up on them with updatedSince (a snapshot of scores carries only the games still on the board, and one of grading carries none).
  • A product you list without a since (or whose connection dropped before its snapshot.end) starts with a snapshot.

A server holds the last 20 000 messages of each product (5 000 for grading): for live at its busiest, a few minutes. Positions work on any of our servers: a reconnect may land on another one and resume there; if that server does not hold your position (it has just started, or re-synced), you get a fresh snapshot instead.

Nothing is skipped in silence. On one connection, every message your filters let through comes, in order; if that cannot be kept (you fall behind, or the server re-syncs), the server closes the stream (4429, 1013). A resume with since gets exactly the messages after it, or a fresh snapshot: never part of them. seq values are not consecutive (they come from a clock), so a jump between two seq is normal and says nothing is missing.

Keeping the connection healthy

  • A heartbeat comes every 15 s when nothing else does. No message for 45 s means the connection is dead: close it and reconnect with since.
  • Connections drop now and then on the way (a network, a proxy): your library reports 1006. That is normal: reconnect with since, with back-off.
  • Any frame you send is accepted and ignored; you do not need to send anything.
  • Keep up. Process messages as they arrive and do heavy work off the socket's thread. A client that falls too far behind is closed with 4429 (reason not keeping up with the stream). Reconnect with since: you lose nothing.

When the stream closes

Reconnect with since after every close except the three marked "no". Servers restart for deploys and there is more than one: do not reconnect only on one code.

Code Meaning What to do Reconnect on its own
1000 Closed normally, by you or by a proxy on the way If you still want the stream, reconnect with since yes
1001 A server or a proxy on the way is shutting down Reconnect with since, after a short random wait (up to 1 s) yes
1006 Never sent: your library reports it when the connection dropped with no close frame (network, proxy) Reconnect with since, with back-off yes
1011 An error of ours while serving the stream Reconnect with since, with back-off; tell us if it repeats yes
1012 The server is restarting (a deploy); another server takes your reconnect Reconnect with since at once, after a random wait of up to 1 s yes
1013 Starting up, or re-synced: what you hold may not match Reconnect with since, after a short back-off yes
4400 A query parameter is not valid; the reason names it Do not retry the same URL: fix the request no
4401 No key, an unknown key, or a key revoked while connected Do not retry: check your key with us no
4403 Your key does not include a product you asked for (or lost it) Reconnect without that product, or ask us to add it no
4429 Either you were not keeping up (reason: not keeping up with the stream) or you are over your connection limit (reason: over your connection limit) Not keeping up: reconnect with since and process faster. Connection limit: close another connection, or wait 30 s before retrying yes

Any other code: reconnect with since, with back-off.

Back-off: wait 1 s, then double up to 30 s, each wait with up to 1 s added at random, so that many clients do not reconnect in the same instant. Go back to 1 s once a connection has lasted a minute. A connection refused before it opens (HTTP 503) counts as a 1013.

Catalog updates

The catalogs (sports, periods, market types, stat keys, leagues, books) are fetched over REST, not sent on the stream. Cache them and refresh them once a day:

  • ids are never renamed or reused;
  • new ids may appear at any time. When a message carries an id you do not know yet, refetch the catalog; if it is still not there, ignore what carries it;
  • gradedPeriodsBySport and gradedLeaguesBySport follow our grader and our daily measurement: they gain and lose entries (see Catalogs).

Every market and selection also carries its display name, so you can show a market whose type you have not cached yet.