Skip to main content

​
What this feed is

The Live Match Feed is a low-latency stream of live game events, reported in real time by trained scouts watching each game. A scout watches the game and reports simple events: a three-pointer is in the air, a penalty was awarded, the batter put the ball in play. Each report updates a small running picture of the game, which is broadcast to every connected consumer with the full updated snapshot attached.
Covers soccer (FIFA World Cup group stage), baseball (MLB), and basketball (NBA, WNBA). The consumer reads are session-addressed under /api (the server resolves each session’s sport); each sport’s event vocabulary and state shape are documented in the Sports overview. This site documents the consumer (read-only) API.
The previous SmartSurfacer Scout Feed API docs have been deprecated and replaced by this site. If you were consuming the Scout Feed API, please migrate to this feed — contact us for assistance.

​
Why it’s fast

Official game data is logged after the play is reviewed and recorded. A scout reports the same fact seconds earlier, so a consumer reacts sooner. For example:

​
What the feed provides

The feed is a read-only data stream. It provides:
  • A live WebSocket that pushes every scout report as a frame carrying the triggering event and the full state snapshot. A dropped frame leaves you at most one event stale — the next frame fully re-syncs you.
  • A history backfill endpoint so a consumer connecting mid-game replays the full tape immediately.
  • A state snapshot on every frame, carrying the derived score and the sport’s live game state.
  • A liveness advisory (scout_status) so you can tell a quiet game from a disconnected scout.

​
Getting started

The typical integration:
  1. GET /api/history/{session} — backfill the event tape
  2. Open wss://.../api/subscribe/{session} — receive live frames
  3. On each frame, append the event to your tape and replace your snapshot with frame.state
Start with the Quickstart.

​
Staying current

The wire can change — field shapes, event types, and behaviour evolve. Every change is recorded on the Changelog, and every breaking change bumps the contractVersion carried on the WebSocket hello frame and on every /history response. Versions count independently per sport, so the schema identity is the pair (sport, contractVersion) — pin your integration to a known pair and assert on both, so a mismatch fails loudly instead of mis-parsing silently. Changes ship immediately on merge; watch the changelog (we also reach out directly for breaking changes).

​
Base URL

The consumer reads are top-level under /api — WS /api/subscribe/{session}, GET /api/history/{session}, GET /api/health/{session}, and GET /api/sessions — the session id alone is the address, and the server resolves its sport. The ungated service liveness probe is GET /health. All endpoints and WebSocket paths in this documentation are relative to this base. See the Sports overview for the sports covered.