Skip to main content
GET /matches/{id}/live returns a complete snapshot of a match in progress — including the current score, match clock, live statistics, event timeline, and what’s happening on the pitch right now. Calling this endpoint requires either the live_scores or live_scores_statistics scope.

​
Find a live match

Before fetching live data, you need a match ID for a game currently in play. Use either of these catalog endpoints (both require the fixtures scope):
  • GET /matches/active?league={id} — returns only NOT_STARTED or STARTED matches for a league.
  • GET /matches?league={id}&status=STARTED — returns only in-play matches.
Once you have a match_id, you’re ready to fetch the live snapshot.

​
Fetch the live snapshot

curl "https://api.sportrixdata.com/api/matches/41282/live" \
  -H "X-API-Key: $KEY"
Example response: 
{
  "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"
}

​
Key fields explained

status — The live snapshot uses lowercase status values that differ from the catalog. Possible values are live (in play), ht (half-time break), ft (full-time), and not_started. clock — The match clock object:
  • minute and second give the current timer, displayed as minute:second (e.g. 75:56).
  • period tells you which phase of the match the clock is in: 1H (first half), 2H (second half), HT (half-time break), or FT (full-time).
  • running is true while the clock is ticking and false during breaks.
  • added indicates added or stoppage time minutes, when applicable.
score — A simple { "home": int, "away": int } object with the current scoreline. phase — Decoded real-time game state describing what’s happening on the pitch right now. The label field gives a human-readable description such as "Dangerous attack", "Corner", "Goal", or "Safe possession". The team field tells you which side is involved. stats — An open-ended map of stat keys to per-side integers. Common soccer keys include shots_on_target, shots_off_target, attacks, dangerous_attacks, possession (as a percentage), corners, yellow_cards, and red_cards. Iterate the keys rather than assuming a fixed set — additional provider stats may appear. events — An ordered timeline of match incidents. Each entry has a minute, type (e.g. goal, yellow_card, substitution), team, and label. The score field on each event captures the scoreline at that moment. ball — The last known ball position, expressed as normalized coordinates (x and y between 0 and 1). This is anchored to the most recent tracked event.

​
REST polling vs. WebSocket

REST /liveWebSocket stream
Best forOn-demand lookups, polling on a schedule, serverless functionsContinuous real-time display, low-latency score tickers
Scope neededlive_scores or live_scores_statisticslive_scores_statistics only
ConnectionStateless HTTP — no persistent connectionPersistent WebSocket connection
UpdatesYou control when you fetchServer pushes every change as it happens
If you only need the current score and clock and don’t require full statistics, the live_scores scope is sufficient for REST polling. For full statistics via WebSocket, you’ll need live_scores_statistics.

​
Fallback behavior and error handling

The /live endpoint serves real-time hot state when available. If there is a brief gap in the live feed, it automatically falls back to the last persisted snapshot — so the endpoint keeps returning data through short interruptions and even after the match ends (returning the final state).
A 404 is returned only when no snapshot has ever been captured for the match — for example, if the match never went live or data collection hasn’t started yet. A match that has finished will still return its final snapshot, not a 404.