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

Group: WebSocket

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.

Plans: Requires Business or Enterprise; on a lower plan the ticket request returns 403 ws_not_available. The tracking:{id} channel needs Enterprise and is refused on Business with channel_forbidden.

Note: 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.

## Example

```text
← { "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 }
```

---

Base URL: https://api.datasportsapi.com. Authenticate each /v2 call with the header `Authorization: Bearer <key>` (secret keys begin with `sk_live_`).
HTML: https://datasportsapi.com/docs/websocket/connect/ · All docs: https://datasportsapi.com/markdown/docs.md · Data reference: https://datasportsapi.com/markdown/reference.md
