WebSocketReal time
Connect
wss:/
Open a connection to the url returned with the ticket. The server first sends welcome — protocol 4 from 2026-10-23 on (protocol 3 earlier that same day, protocol 2 from 2026-10-19); channels and frame types are added without raising that number, so ignore any frame type you do not recognise — and then you subscribe to channels. A subscription opens with a snapshot (or, when a lastSeq replay finishes or you subscribe again, with a subscribed frame), and every later frame carries a per-channel seq that rises by one each time. Treat seq as opaque: it does not start at 0, and after a reconnect a different server may answer, so the next value can be lower or higher than the last one you saw — the snapshot or subscribed frame you then receive sets the new starting point. Whenever a fixture enters the set of a livescores, sport:{slug}, league:{id} or team:{id} channel — it kicked off, or the server sees it for the first time — it arrives as a fixture frame holding the complete Fixture. Later deltas patch it, and deltas only ever touch fixtures you have already been sent; when a fixture leaves the set (finished, canceled), one final delta reports that.
Any /v2 call can also come back with one of the common errors.
← { "type": "welcome", "protocol": 4, "heartbeatMs": 30000, "maxChannels": 50, "replay": true }
→ { "type": "subscribe", "channel": "livescores" }
← { "type": "snapshot", "channel": "livescores", "seq": 1760800000000, "ts": 1760800000000, "data": [ Fixture, … ] }
← { "type": "fixture", "channel": "livescores", "seq": 1760800000001, "ts": 1760800002480,
"id": 201330, "sport": "basketball", "data": { "id": 201330, "sport": "basketball",
"status": { "type": "inprogress", "phase": "inprogress", "code": 13, "description": "1st quarter", "period": "period1", "finish": null }, … } }
← { "type": "delta", "channel": "livescores", "seq": 1760800000002, "ts": 1760800004120,
"id": 201324, "sport": "football",
"changes": { "awayScore": { "current": 1, "periods": { "period2": 1 } } } }
← { "type": "delta", "channel": "livescores", "seq": 1760800000003, "ts": 1760800009310,
"id": 201324, "sport": "football",
"changes": { "status": { "code": 100, "description": "Ended", "type": "finished", "phase": "finished",
"finish": "regular", "period": null },
"winner": "away", "clock": null } }
// Reconnect with the last seq you hold (Business and Enterprise): the missed frames, then subscribed
→ { "type": "subscribe", "channel": "livescores", "lastSeq": 1760800000003 }
← { "type": "subscribed", "channel": "livescores", "seq": 1760800000003, "ts": 1760800030000, "replayed": 0 }
// fixture:{id} — play by play appended from index start (since 2026-10-24)
← { "type": "playByPlay", "channel": "fixture:201330", "seq": 1760800040000, "ts": 1760800041900, "id": 201330, "sport": "basketball",
"start": 117, "total": 118, "entries": [ { "type": "scoreChange", "side": "home", "period": "period3", "periodSecond": 401,
"text": "Jump shot made", "homeScore": 69, "awayScore": 74, "scoreType": "twoPointer", … } ] }
← { "type": "shotmap", "channel": "fixture:201324", "seq": 1760800050000, "ts": 1760800050500, "id": 201324, "sport": "football",
"shots": [ { "side": "away", "outcome": "goal", "minute": 37, "period": "period1", … }, … ] }
→ { "type": "subscribe", "channel": "fixture:999999999999" }
← { "type": "error", "code": "unknown_fixture", "channel": "fixture:999999999999", "message": "no fixture with that id", "ts": 1760800031000 }
→ { "type": "unsubscribe", "channel": "sport:tennis" }
← { "type": "error", "code": "not_subscribed", "channel": "sport:tennis", "message": "not subscribed to this channel", "ts": 1760800032000 }Channels
| Channel | Plans | Snapshot | Updates |
|---|---|---|---|
livescores | Business and up | Fixture[]: every fixture in progress | a fixture frame (id, sport, data: Fixture) once a fixture joins, then a delta (id, sport, changes) each time one you hold changes |
sport:{slug} | Business and up | Fixture[]: the sport's fixtures in progress | a fixture frame once a fixture joins, then a delta (id, sport, changes) each time one you hold changes |
fixture:{id} | Business and up | Fixture, or null when unavailable (an id we never issued answers error unknown_fixture and does not count toward maxChannels) | Deltas (id, sport, changes). During play, three more frame types follow whenever their data changes: an events frame (id, sport, events: the full keyed list, changes: added / updated / removed), a statistics frame (id, sport, statistics) and a lineups frame (id, sport, lineups). None of this comes through the live feed, so the server polls REST for it: statistics and lineups every 30 s, events about 20 s and again 45 s after any score, red card or status change, with a 30 s sweep on top. A frame goes out only if something changed. Since 2026-11-04 this starts before kick-off: once the source publishes or confirms lineups, a delta updates lineupsAvailable / lineupsConfirmed and a lineups frame arrives seconds later. Since 2026-10-24 there are playByPlay frames too (id, sport, start, total, entries from index start on) for football and basketball, polled every 20 s: hold on to the first start entries you have and append the new ones, and reread REST when start lies past the end of what you hold. Football adds momentum frames (id, sport, momentum: the full object) plus shotmap frames (id, sport, shots: the full list), polled every 30 s and sent on a change, for no more than 20 subscribed fixtures at a time (the most subscribed ones). Football also gets winProbability frames (id, sport, model, point), sent once an outcome shifts by 1 pp or more, and commentary frames (id, sport, entry) for every new AI commentary entry. |
league:{id} | Business and up | Fixture[]: the league's fixtures in progress (our league id; an unknown id answers error unknown_league) | a fixture frame once a fixture joins, then a delta (id, sport, changes) each time one you hold changes |
team:{id} | Business and up | Fixture[]: the team's fixtures in progress, home or away (our team id; an unknown id answers error unknown_team). Since 2026-11-04 | a fixture frame once one of its fixtures joins, then a delta (id, sport, changes) each time one you hold changes: what a league channel sends, narrowed to one team |
odds:{id} | Business and up | Odds: the fixture's markets, exactly as GET /v2/fixtures/{id}/odds returns them (our fixture id; an unknown id answers error unknown_fixture). Since 2026-11-04 | odds frames (id, sport, updatedAt, markets: each changed market in full; removed: keys of markets that no longer exist). Store each market under its key, overwriting any copy you have, and drop the removed keys. Price moves reach you within about a second, straight off the source's live odds feed; suspensions, new lines and settlement come from polling REST, every 30 s in play and every 2 minutes before kick-off. Odds travel on this channel only. |
tracking:{id} | Enterprise | Since 2026-11-12, Enterprise only (Business connections are refused with error channel_forbidden). TrackingSnapshot: { fixtureId, tracking: the TrackingSummary (null until anything has been recorded), ball: the latest 100 BallFrames, events: the latest 100 TrackedEvents } (our fixture id; an unknown id answers error unknown_fixture) | ball frames (id, sport, frame: BallFrame), one per new ball position, pushed roughly a second after the source captures it: around 14 a minute of football play and around one per tennis shot; trackedEvent frames (id, sport, event: TrackedEvent), live for tennis and football, while football passes and most basketball events come in one burst with the post-match read (keep events in a map by key, since a repeated key is the same event sent again); and trackingStatus frames (id, sport, final, complete), sent once the match has ended and again once the post-match data is in: the cue to read the REST tracking endpoints again. |
race:{id} | Business and up | RaceSnapshot: { race: Race, session, results: RaceResult[] }: every session of the race, plus the one running now (or else the most recent to finish) with its classification. An id that matches no race answers error unknown_race | A race frame (id, sport, data: Race) whenever a session begins or ends or anything else about the race changes; a raceResults frame (id, sport, session, results) whenever the classification of the current session moves. Race sports lack a live feed, so both come from polling REST: the race every 60 s whenever a session is running or due to start in the next 15 minutes, live results every 30 s, and, for 30 minutes after a session ends, its final results every 60 s, since the source adds the winner's time and the fastest lap only minutes after the flag. Nothing is sent unless something changed. |
Client frames
{ "type": "subscribe", "channel": "…", "lastSeq"?: n }Starts a channel; the answer is a snapshot. With replay (Business and up), send the last seq you hold and the missed frames are replayed instead, followed by { "type": "subscribed", "channel", "seq", "ts", "replayed" } (frames are held for 5 minutes on each channel; a gap older than that gets a fresh snapshot). Subscribing to a channel you are already on answers subscribed with replayed 0.
{ "type": "unsubscribe", "channel": "…" }Leaves a channel. The server confirms with { "type": "unsubscribed", "channel", "ts" }; if this connection never joined that channel, the reply is error not_subscribed.
{ "type": "resync", "channel": "…" }Sends the whole channel state again as a new snapshot. Works only on channels this connection has joined; anything else answers error not_subscribed.
{ "type": "ping" }A ping at the application level; the server replies { "type": "pong", "ts": <ms> }.
Close codes
- 1008
- The ticket is invalid, expired or already used: mint a new one. On a connection that is already open, it means its API key was revoked, the account was suspended, or this WebSocket grade is no longer part of the plan (the reason "plan changed; reconnect" means a new ticket is enough).
- 1012
- The server is restarting for a deploy (reason "server restarting; reconnect"). Not an error: open a new connection right away with a fresh ticket, then resubscribe passing the last seq in your copy; another server answers. The official SDKs handle this on their own.
- 1013
- Your plan's limit on concurrent connections is reached; the count covers all servers, not just the one you reached. Close one of your other connections, or try again later.
WsErrorCodeCodes that a WebSocket error frame can carry.11 values
Codes that a WebSocket error frame can carry.
bad_frameThe frame is not valid JSON, does not match any known shape, or is missing a required field;messagenames that field (e.g. "channel: required").unknown_channelThe channel name is not one we offer, or its sport slug is unknown.channel_forbiddenYour plan’s tier does not include this channel.unknown_leagueleague:{id} refers to a league id DataSportsAPI never issued (take ids from /v2/leagues or from a fixture’s league). The REST API returns 404 not_found for the same id.unknown_fixtureThe id in fixture:{id} — or in odds:{id} (from 2026-11-04) or tracking:{id} (from 2026-11-12) — is not a fixture DataSportsAPI issued; REST answers 404 not_found for that id. It does not count as one of your channels.unknown_racerace:{id} does not point to a race: it is a season or session id, or an id DataSportsAPI never issued. /v2/races/{id} returns 404 for the same id. It does not count as one of your channels.unknown_teamteam:{id} refers to a team id DataSportsAPI never issued (take ids from a fixture’s home / away or from /v2/teams). The REST API returns 404 not_found for the same id. Available since 2026-11-04.not_subscribedA resync / unsubscribe targeted a channel this connection has not joined.too_many_channelsThis connection has reached its maxChannels limit.snapshot_failedBuilding the snapshot failed; retry with resync. For league:{id}, this also happens when the league id could not be verified at that moment, in which case subscribe again.rate_limitedThis connection sent over 60 frames within 10 seconds; further frames are discarded until the window resets.
Appears inWsError
seq is skipped, send resync, or, with replay (Business and up), subscribe again with lastSeq to have the gap replayed. Close code 1012 signals a deploy in progress: reconnect straight away, and a different server picks you up.Server frames
Every frame the server can send, field by field. The changes of a delta is a FixturePatch: merge it deeply into your copy of that Fixture. On list channels, a fixture frame delivers a complete new Fixture to add.
WsWelcomeThe server sends this frame first, as soon as the connection opens.5 fields
The server sends this frame first, as soon as the connection opens.
type"welcome"- —
protocolinteger- Version of the protocol in use. It has been 4 since the evening of 2026-10-23 (from then on, a fixture joining a list channel is delivered as a
fixtureframe); it was 3 from 2026-10-23 and 2 from 2026-10-19. Channels and frame types are added without changing this number (odds:{id} on 2026-11-04, tracking:{id} on 2026-11-12, the timelineEvent and playerFrame frames on tracking:{id} on 2026-11-13), so skip any frame type you do not recognise. heartbeatMsinteger- Interval between server pings. Reply to them (browsers do this automatically) or the connection is closed.
maxChannelsinteger- Maximum number of channels this connection may subscribe to.
replayboolean- True when your plan includes
lastSeqreplay.
WsSnapshotThe complete current state of a channel, delivered when you subscribe and again whenever you resync.5 fields
The complete current state of a channel, delivered when you subscribe and again whenever you resync.
type"snapshot"- —
channelstring- —
seqinteger- Current sequence number of the channel. Treat it as an opaque, increasing counter that does not start at 0; the following delta carries seq + 1.
tsinteger- Server timestamp in Unix milliseconds.
datasince 2026-11-04Fixture[] | Fixture | RaceSnapshot | Odds | TrackingSnapshot | null- Depends on the channel. livescores / sport:{slug} / league:{id} / team:{id} carry a Fixture[]: for league:{id}, that league’s in-progress fixtures; for team:{id} (since 2026-11-04), that team’s in-progress fixtures, home and away. fixture:{id} carries a Fixture and race:{id} a RaceSnapshot; odds:{id} (since 2026-11-04) carries an Odds matching GET /v2/fixtures/{id}/odds, and tracking:{id} (since 2026-11-12) a TrackingSnapshot. Each of these four is null when there is no data.
WsDeltaSent when a single fixture changes. On the four list channels (livescores, sport:{slug}, league:{id}, team:{id}), every delta concerns a fixture the channel already sent you, either in its snapshot or as a fixture frame, and a fixture that drops out of the channel (finished, canceled) receives one final delta reporting that. Deltas cover both live-feed updates and the corrections a board refresh produces. A score that goes DOWN (a goal disallowed, a basket corrected) arrives within 1.5 s of the source sending it; the delay lets us drop the brief flaps when the source re-sends an older score. A REST refetch of /fixtures/{id} may still be a few seconds ahead, so resync from time to time if you need exact values.7 fields
Sent when a single fixture changes. On the four list channels (livescores, sport:{slug}, league:{id}, team:{id}), every delta concerns a fixture the channel already sent you, either in its snapshot or as a fixture frame, and a fixture that drops out of the channel (finished, canceled) receives one final delta reporting that. Deltas cover both live-feed updates and the corrections a board refresh produces. A score that goes DOWN (a goal disallowed, a basket corrected) arrives within 1.5 s of the source sending it; the delay lets us drop the brief flaps when the source re-sends an older score. A REST refetch of /fixtures/{id} may still be a few seconds ahead, so resync from time to time if you need exact values.
type"delta"- —
channelstring- —
seqinteger- One more than the previous seq on this channel. A gap means you lost a delta — send resync.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
changesFixturePatch- A partial Fixture that uses the same field names and nesting as the full object. Deep-merge it into the Fixture you store: objects are merged key by key, while every other value (null included) overwrites what you have. No fields beyond those listed for FixturePatch are ever sent.
WsFixtureOn the four list channels (livescores, sport:{slug}, league:{id}, team:{id}): the channel’s set gained a fixture — after kick-off, or when the server first sees it. The frame carries the complete Fixture, exactly as a snapshot would contain it. Append it to your list and apply subsequent deltas to it. fixture:{id} channels never receive this frame.7 fields
On the four list channels (livescores, sport:{slug}, league:{id}, team:{id}): the channel’s set gained a fixture — after kick-off, or when the server first sees it. The frame carries the complete Fixture, exactly as a snapshot would contain it. Append it to your list and apply subsequent deltas to it. fixture:{id} channels never receive this frame.
type"fixture"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the counter is shared with deltas.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
dataFixture- A match, in the same shape used by every endpoint and by WebSocket snapshots.
WsSubscribedAcknowledges a subscribe that produced no snapshot: either a lastSeq replay (sent once the replayed frames have gone out) or a repeat subscribe to a channel you already hold.5 fields
Acknowledges a subscribe that produced no snapshot: either a lastSeq replay (sent once the replayed frames have gone out) or a repeat subscribe to a channel you already hold.
type"subscribed"- —
channelstring- —
seqinteger- Current seq of the channel once the replay is done; the following delta carries seq + 1.
tsinteger- Server timestamp in Unix milliseconds.
replayedinteger- Number of frames the replay delivered. 0 means you missed nothing, or that you were already subscribed to the channel.
WsWinProbabilityOn fixture:{id} channels for football fixtures in play: the win-probability estimate shifted by one percentage point or more (evaluated whenever the fixture changes and once per minute). point matches the endpoint’s current, including why it moved, and point.at is the moment it was calculated. It is NOT a point on the stored curve, whose per-minute points fall at the end of each minute; for a chart, fetch GET /v2/fixtures/{id}/win-probability once and then refresh it with ?since=.8 fields
On fixture:{id} channels for football fixtures in play: the win-probability estimate shifted by one percentage point or more (evaluated whenever the fixture changes and once per minute). point matches the endpoint’s current, including why it moved, and point.at is the moment it was calculated. It is NOT a point on the stored curve, whose per-minute points fall at the end of each minute; for a chart, fetch GET /v2/fixtures/{id}/win-probability once and then refresh it with ?since=.
type"winProbability"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the channel’s deltas use the same counter.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sport"football"- Slug of the fixture’s sport; win probability exists only for football.
modelWinProbabilityModel- Version of the model that produced the estimate. Each version is described in the docs, and new ones are announced in the changelog.
pointWinProbabilityPoint- One point on the win-probability curve: the estimate together with the reason it was produced.
WsCommentaryOn fixture:{id} channels for football fixtures: a fresh AI commentary entry has been produced. Keep the two counters apart: the frame’s seq belongs to the channel (and is shared with deltas), whereas entry.seq numbers the entry within GET /v2/fixtures/{id}/commentary.7 fields
On fixture:{id} channels for football fixtures: a fresh AI commentary entry has been produced. Keep the two counters apart: the frame’s seq belongs to the channel (and is shared with deltas), whereas entry.seq numbers the entry within GET /v2/fixtures/{id}/commentary.
type"commentary"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the channel’s deltas use the same counter.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sport"football"- Slug of the fixture’s sport; commentary exists only for football.
entryCommentaryEntry- A single AI-written commentary entry.
WsEventsOn fixture:{id} channels for fixtures in play: the list of match events (goals, cards, substitutions, VAR decisions, periods, …) has changed. Because the live feed contains no events, the server pulls them from REST: roughly 20 s and 45 s after every change of score, red cards or status (goals reach the source’s event list 18–33 s after the score changes), and every 30 s during play, since cards and substitutions trigger no signal. A frame goes out only when the list differs. A disallowed goal shows up in changes.removed, and only after REST has confirmed it. Each frame holds the complete list, so missing one does no harm; fetch GET /v2/fixtures/{id}/events for the state before the first frame arrives.8 fields
On fixture:{id} channels for fixtures in play: the list of match events (goals, cards, substitutions, VAR decisions, periods, …) has changed. Because the live feed contains no events, the server pulls them from REST: roughly 20 s and 45 s after every change of score, red cards or status (goals reach the source’s event list 18–33 s after the score changes), and every 30 s during play, since cards and substitutions trigger no signal. A frame goes out only when the list differs. A disallowed goal shows up in changes.removed, and only after REST has confirmed it. Each frame holds the complete list, so missing one does no harm; fetch GET /v2/fixtures/{id}/events for the state before the first frame arrives.
type"events"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the channel’s deltas use the same counter.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
eventsKeyedIncident[]- The FULL events list as it stands, in chronological order — the incidents GET /v2/fixtures/{id}/events returns, keys included. Replace your copy with it.
changesIncidentChanges- The difference between this events frame and the one before it.
WsStatisticsOn fixture:{id} channels for fixtures in play: the match statistics have changed, and the frame carries the complete object as returned by GET /v2/fixtures/{id}/statistics. The server reads REST every 30 s while at least one client is subscribed, plus a final read after full time, and emits a frame only when the content differs. Figures typically trail the action by ~30–60 s.7 fields
On fixture:{id} channels for fixtures in play: the match statistics have changed, and the frame carries the complete object as returned by GET /v2/fixtures/{id}/statistics. The server reads REST every 30 s while at least one client is subscribed, plus a final read after full time, and emits a frame only when the content differs. Figures typically trail the action by ~30–60 s.
type"statistics"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the channel’s deltas use the same counter.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
statisticsStatistics- The match statistics, broken down by period.
WsLineupsOn fixture:{id} channels for fixtures in play: the lineups have changed. The frame carries the whole object that GET /v2/fixtures/{id}/lineups returns, including each player’s statistics. While someone is subscribed the server checks every 30 s, stopping once the lineups are confirmed and have stayed the same for 10 minutes. Substitutions are delivered as events instead.7 fields
On fixture:{id} channels for fixtures in play: the lineups have changed. The frame carries the whole object that GET /v2/fixtures/{id}/lineups returns, including each player’s statistics. While someone is subscribed the server checks every 30 s, stopping once the lineups are confirmed and have stayed the same for 10 minutes. Substitutions are delivered as events instead.
type"lineups"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the channel’s deltas use the same counter.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
lineupsLineups- The lineups for each side.
WsPlayByPlayOn fixture:{id} channels, for football and basketball matches in play: the source’s play-by-play commentary has new or changed text. While at least one client is subscribed the server re-reads REST every 20 s (the source’s own page updates every 15–20 s), and once more after full time. A frame is sent only when the list differs, and it starts at the first entry that changed. For the state before the first frame, call GET /v2/fixtures/{id}/play-by-play.9 fields
On fixture:{id} channels, for football and basketball matches in play: the source’s play-by-play commentary has new or changed text. While at least one client is subscribed the server re-reads REST every 20 s (the source’s own page updates every 15–20 s), and once more after full time. A frame is sent only when the list differs, and it starts at the first entry that changed. For the state before the first frame, call GET /v2/fixtures/{id}/play-by-play.
type"playByPlay"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the channel’s deltas use the same counter.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
startinteger- 0-based position, in the full list, of the first item in
entries. Retain your firststartentries, discard everything after them and appendentries. Normally equal to the length of your list (new lines added at the end); lower when the source edited or deleted a line. totalinteger- Current length of the full list (start + entries.length). If
startis beyond the end of your list, you are out of sync — reload GET /v2/fixtures/{id}/play-by-play. entriesPlayByPlayEntry[]- Entries from position
startonwards, oldest first, in the form GET /v2/fixtures/{id}/play-by-play returns them.
WsMomentumOn fixture:{id} channels for football fixtures in play: the momentum graph has changed. The frame holds the complete object as returned by GET /v2/fixtures/{id}/momentum; with one point per minute, expect roughly one frame a minute. While anyone is subscribed the server checks every 30 s (and once more after full time) and only sends a frame if something changed.7 fields
On fixture:{id} channels for football fixtures in play: the momentum graph has changed. The frame holds the complete object as returned by GET /v2/fixtures/{id}/momentum; with one point per minute, expect roughly one frame a minute. While anyone is subscribed the server checks every 30 s (and once more after full time) and only sends a frame if something changed.
type"momentum"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the channel’s deltas use the same counter.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
momentumMomentum- The momentum graph: a value per game in tennis, or per minute in football, basketball, handball, ice hockey and the like.
WsShotmapOn fixture:{id} channels for football fixtures in play: the shot map has changed, through either a new shot or a correction by the source. While anyone is subscribed the server checks every 30 s (and once more after full time) and only sends a frame if something changed. Shots typically appear ~30–60 s after they happen.7 fields
On fixture:{id} channels for football fixtures in play: the shot map has changed, through either a new shot or a correction by the source. While anyone is subscribed the server checks every 30 s (and once more after full time) and only sends a frame if something changed. Shots typically appear ~30–60 s after they happen.
type"shotmap"- —
channelstring- —
seqinteger- One more than the previous seq on this channel; the channel’s deltas use the same counter.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
shotsShot[]- The current shot map in FULL, oldest first, as returned by GET /v2/fixtures/{id}/shotmap. Overwrite your copy with it.
WsRaceOn race:{id}: something about the race changed, such as a session starting or finishing, or a status or schedule update. The frame carries the complete Race as returned by GET /v2/races/{id}. Since the live feed has no data for race sports, the server reads REST every 60 s while a session is running or due to begin within 15 minutes.7 fields
On race:{id}: something about the race changed, such as a session starting or finishing, or a status or schedule update. The frame carries the complete Race as returned by GET /v2/races/{id}. Since the live feed has no data for race sports, the server reads REST every 60 s while a session is running or due to begin within 15 minutes.
type"race"- —
channelstring- —
seqinteger- One more than the previous seq on this channel.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Race id assigned by DataSportsAPI.
sportstring- Slug of the race’s sport (motorsport, cycling).
dataRace- A race: a motorsport weekend with practice, qualifying, sprint and race, or a cycling event — one-day or stage race.
WsRaceResultsOn race:{id}: the classification of a session has changed. The server checks every 30 s while the session is running and one last time when it finishes, and sends a frame only when something differs.8 fields
On race:{id}: the classification of a session has changed. The server checks every 30 s while the session is running and one last time when it finishes, and sends a frame only when something differs.
type"raceResults"- —
channelstring- —
seqinteger- One more than the previous seq on this channel.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Race id assigned by DataSportsAPI.
sportstring- Slug of the race’s sport.
sessioninteger | null- The session this classification belongs to.
resultsRaceResult[]- The full classification of the session, as returned by /v2/races/{id}/results?session=.
WsOddsOn odds:{fixtureId}: prices have moved (available since 2026-11-04). Price changes, both in-play and pre-match, come from the source’s live odds feed and reach you within roughly a second. Suspensions, newly added markets and settlement flags rely on a REST re-read, every 30 s during the match and every 2 minutes beforehand. Hold on to the snapshot (an Odds, as returned by GET /v2/fixtures/{id}/odds) and merge every frame into it by market key. Odds travel exclusively on odds:{id}; no other channel includes them.9 fields
On odds:{fixtureId}: prices have moved (available since 2026-11-04). Price changes, both in-play and pre-match, come from the source’s live odds feed and reach you within roughly a second. Suspensions, newly added markets and settlement flags rely on a REST re-read, every 30 s during the match and every 2 minutes beforehand. Hold on to the snapshot (an Odds, as returned by GET /v2/fixtures/{id}/odds) and merge every frame into it by market key. Odds travel exclusively on odds:{id}; no other channel includes them.
type"odds"- —
channelstring- —
seqinteger- One more than the previous seq on this channel.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sportstring- Slug of the fixture’s sport.
updatedAtstring (ISO-8601 UTC)- Time at which these prices came in.
marketsOddsMarket[]- Markets that changed, each sent in FULL with all its choices. Swap out your market with the matching
key, or add it if you do not have one yet. removedstring[]- Keys of markets the bookmaker has withdrawn (for example a handicap line that moved, or a closed market). Remove them from your copy.
WsBallOn tracking:{fixtureId} (since 2026-11-12): one new position of the live ball track — about 14 a minute of football play, about one per tennis shot — sent within roughly a second after the source records it. Add it to the end of the ball list you got with the snapshot.7 fields
On tracking:{fixtureId} (since 2026-11-12): one new position of the live ball track — about 14 a minute of football play, about one per tennis shot — sent within roughly a second after the source records it. Add it to the end of the ball list you got with the snapshot.
type"ball"- —
channelstring- —
seqinteger- One more than the previous seq on this channel.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sport"football" | "tennis" | "basketball" | "ice-hockey" | "darts"- Slug of the fixture’s sport.
frameBallFrame- The new position of the ball (football, tennis).
WsTrackedEventOn tracking:{fixtureId} (since 2026-11-12): one more tracked event. Tennis sends each serve, point, ball position and player position live. Football sends, live and about 18 a minute, its goals, shots, cards, substitutions, set pieces and the flow-of-play types (possessionChange, flowAttack, flowDangerousAttack, flowBallSafe), then the passes in one burst with the post-match read. Basketball events come mostly in that burst. Keep events keyed by key; receiving a key you already have means the same event again.7 fields
On tracking:{fixtureId} (since 2026-11-12): one more tracked event. Tennis sends each serve, point, ball position and player position live. Football sends, live and about 18 a minute, its goals, shots, cards, substitutions, set pieces and the flow-of-play types (possessionChange, flowAttack, flowDangerousAttack, flowBallSafe), then the passes in one burst with the post-match read. Basketball events come mostly in that burst. Keep events keyed by key; receiving a key you already have means the same event again.
type"trackedEvent"- —
channelstring- —
seqinteger- One more than the previous seq on this channel.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sport"football" | "tennis" | "basketball" | "ice-hockey" | "darts"- Slug of the fixture’s sport.
eventTrackedEvent- A tracked play-by-play event and where on the pitch or court it happened (football, tennis, basketball). Tennis events are sent live; football ones too, usually some 9 seconds behind play and rarely past 15 (flow of play, set pieces, shots, goals, cards, substitutions, while passes and finer detail follow with the post-match read). Basketball events mostly come with the post-match read.
WsTimelineEventOn tracking:{fixtureId} (since 2026-11-13): one basketball, ice hockey or darts timeline event, roughly 5 seconds after the moment (about 4 – 8 a minute in basketball, about 25 – 30 in darts). With upsert, add it or overwrite the one under the same key (a revision; earlier positions in a period can shift once its shots show which way the side attacks); with remove, the source has withdrawn it. Start from the snapshot’s timeline and apply every frame by key.9 fields
On tracking:{fixtureId} (since 2026-11-13): one basketball, ice hockey or darts timeline event, roughly 5 seconds after the moment (about 4 – 8 a minute in basketball, about 25 – 30 in darts). With upsert, add it or overwrite the one under the same key (a revision; earlier positions in a period can shift once its shots show which way the side attacks); with remove, the source has withdrawn it. Start from the snapshot’s timeline and apply every frame by key.
type"timelineEvent"- —
channelstring- —
seqinteger- One more than the previous seq on this channel.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sport"football" | "tennis" | "basketball" | "ice-hockey" | "darts"- Slug of the fixture’s sport.
opTimelineOp- How this frame changes the timeline you keep.
keystring- Key of the event (TimelineEvent.key) to add, overwrite or delete.
eventTimelineEvent | null- For upsert, the event; null for remove.
WsPlayerFrameOn tracking:{fixtureId}, NBA games only (since 2026-11-13): one player frame with the ball and every player, five per second, about 1–2 seconds behind play and delivered in batches of five each second. Unlike every other frame it has NO seq and is never replayed: it samples the current state and the newest frame wins. Replace the snapshot’s playerFrame with it, and show the frames of one batch in frame order, spacing them 0.2 s. A connection that lags behind receives the newer frames and misses the older ones.6 fields
On tracking:{fixtureId}, NBA games only (since 2026-11-13): one player frame with the ball and every player, five per second, about 1–2 seconds behind play and delivered in batches of five each second. Unlike every other frame it has NO seq and is never replayed: it samples the current state and the newest frame wins. Replace the snapshot’s playerFrame with it, and show the frames of one batch in frame order, spacing them 0.2 s. A connection that lags behind receives the newer frames and misses the older ones.
type"playerFrame"- —
channelstring- —
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sport"football" | "tennis" | "basketball" | "ice-hockey" | "darts"- Slug of the fixture’s sport (basketball).
framesince 2026-11-13PlayerFrame- One player-tracking frame (basketball, NBA games only; since 2026-11-13): the ball and every player on the court, five frames a second, in a court frame where the home side attacks x = 100 in every period, although the teams swap baskets at half-time. Each team’s direction is read per period from where its shots go up, so a live frame from the first seconds, before any shot, can arrive mirrored (a later REST read is corrected). No frames during half-time, and none for a game that was not recorded live.
WsTrackingStatusOn tracking:{fixtureId} (since 2026-11-12): sent when the match ends (final) and again when its post-match data has been read (complete).8 fields
On tracking:{fixtureId} (since 2026-11-12): sent when the match ends (final) and again when its post-match data has been read (complete).
type"trackingStatus"- —
channelstring- —
seqinteger- One more than the previous seq on this channel.
tsinteger- Server timestamp in Unix milliseconds.
idinteger- Fixture id assigned by DataSportsAPI.
sport"football" | "tennis" | "basketball" | "ice-hockey" | "darts"- Slug of the fixture’s sport.
finalboolean- The match has ended; the ball track is closed.
completeboolean- The post-match data has been read: call the REST tracking endpoints again to get the settled events, timeline and player names.
WsUnsubscribedAcknowledges that you have left a channel.3 fields
Acknowledges that you have left a channel.
type"unsubscribed"- —
channelstring- —
tsinteger- Server timestamp in Unix milliseconds.
WsPingHeartbeat at the application level, emitted every heartbeatMs alongside the protocol-level ping. You do not need to answer it.2 fields
Heartbeat at the application level, emitted every heartbeatMs alongside the protocol-level ping. You do not need to answer it.
type"ping"- —
tsinteger- Server timestamp in Unix milliseconds.
WsPongThe server’s answer to a { "type": "ping" } you sent.2 fields
The server’s answer to a { "type": "ping" } you sent.
type"pong"- —
tsinteger- Server timestamp in Unix milliseconds.
WsErrorThe server rejected a frame you sent. Your connection remains open.5 fields
The server rejected a frame you sent. Your connection remains open.
type"error"- —
codeWsErrorCode- Machine-readable code of the WebSocket error.
messagestring- —
channelonly if changedstring- —
tsinteger- Server timestamp in Unix milliseconds.