Skip to main content
The live snapshot is the shared data shape that carries real-time match state across both REST and WebSocket surfaces. Whether you poll on demand or receive pushed updates, the structure is always the same.

​
Used by

  • GET /matches/{id}/live — returns the snapshot directly
  • GET /matches/{id}/result — returns the snapshot as half_time and full_time objects
  • WebSocket snapshot and update frames — the snapshot is the data field

​
Top-level fields

​
v
integer
required
Schema version. Currently 1.
​
match_id
integer
Your match id. Present on WebSocket frames for multiplexing; omitted on REST responses.
​
provider
object
Upstream reference ids. Clients can usually ignore this object.
​
sport
string
required
Normalized sport name, e.g. "soccer".
​
competition
string
required
League or competition name, e.g. "USA MLS Next Pro League".
​
home
string
required
Home team name.
​
away
string
required
Away team name.
​
status
string
required
Current match state: live, ht (half-time), ft (full-time), or not_started.
​
clock
object
required
Match clock. See Clock below.
​
score
object
required
Current score as {"home": int, "away": int}.
​
phase
object
required
Decoded current game state. See Phase below.
​
stats
object
required
Map of stat key → {"home": int, "away": int}. See Statistics.
​
events
array | null
Timeline incidents. null if no events have occurred yet. See Events.
​
ball
object
Last event-anchored ball position on the pitch. See Ball Position.
​
updated_at
datetime
required
When this snapshot was produced, in ISO 8601 UTC.

​
Clock

The displayable timer is minute:second — for example, 75:56.

​
Phase

The phase object describes what is happening on the pitch right now.

​
Full example

{
  "v": 1,
  "match_id": 41282,
  "provider": {"stat_id": "151350409062M1_1"},
  "sport": "soccer",
  "competition": "USA MLS Next Pro League",
  "home": "Vancouver Whitecaps II",
  "away": "The Town",
  "status": "live",
  "clock": {"minute": 75, "second": 56, "period": "2H", "running": true, "added": 0},
  "score": {"home": 3, "away": 2},
  "phase": {"vc": "21002", "team": "away", "code": "1002", "label": "Dangerous attack"},
  "stats": {
    "shots_on_target": {"home": 4, "away": 2},
    "possession": {"home": 56, "away": 44},
    "corners": {"home": 5, "away": 3}
  },
  "events": [
    {"minute": "60", "type": "goal", "team": "home", "label": "Goal", "score": "1-0"}
  ],
  "ball": {"x": 0.91, "y": 0.5, "event": "goal", "minute": "60"},
  "updated_at": "2026-06-18T02:56:50Z"
}