Skip to content

Livematches in play

Demo: Matchboard, opens in a new tab
Docs v2

WebSocketReal time

Connect

WS

wss://api.datasportsapi.com/?ticket={ticket}

Business and up

View as Markdown

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.

With protocol 4 you must process the fixture frame: a client that ignores it misses every match kicking off while it is connected. The changes in a delta form a partial Fixture — merge them field by field into your copy. The merge goes into nested objects too (homeScore, clock, cricket innings, …); they are never swapped out whole, and since 2026-11-14 a clock that changed arrives with all of its fields. Every frame includes ts, the server time in Unix milliseconds. Close codes: 1008 means the ticket is invalid or expired (mint another) or, on a connection that is already open, that its API key was revoked, the account was suspended or the plan changed — the close reason says which, and these are checked the moment they happen and once a minute; 1012 means the server is restarting for a deploy — reconnect straight away and subscribe again, passing the last seq in your copy, and another server takes the connection; 1013 means your plan’s limit on concurrent connections has been reached, counted across all servers. Every heartbeatMs the server sends both a protocol-level ping and a ping frame, and drops connections that stop responding. If no frame at all has come in for 2.5 heartbeats, treat the connection as dead even though it never closed (a laptop waking from sleep or a switch of network leaves sockets like that): drop it, reconnect with your last seq and reload over REST whatever you display — the official SDKs do this on their own and tell you that they reconnected. When a score goes DOWN (a goal ruled out, a corrected basket), you get it with the lowered period scores within 1.5 s of the source reporting it (5 s in football). We hold it back because the source sometimes briefly repeats an older score; since 2026-10-24 those flaps are dropped.

Any /v2 call can also come back with one of the common errors.

Frame flow
← { "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

ChannelPlansSnapshotUpdates
livescoresBusiness and upFixture[]: every fixture in progressa 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 upFixture[]: the sport's fixtures in progressa fixture frame once a fixture joins, then a delta (id, sport, changes) each time one you hold changes
fixture:{id}Business and upFixture, 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 upFixture[]: 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 upFixture[]: the team's fixtures in progress, home or away (our team id; an unknown id answers error unknown_team). Since 2026-11-04a 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 upOdds: 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-04odds 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}EnterpriseSince 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 upRaceSnapshot: { 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_raceA 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; message names 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

Reconnecting: mint a new ticket every time, because a ticket works once. Apply deltas on top of the snapshot you hold; when a 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 fixture frame); 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 lastSeq replay.
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 first start entries, discard everything after them and append entries. 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 start is beyond the end of your list, you are out of sync — reload GET /v2/fixtures/{id}/play-by-play.
entriesPlayByPlayEntry[]
Entries from position start onwards, 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.