> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportrix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Live Match Scores and Statistics via REST API

> Use GET /matches/{id}/live to retrieve the latest in-play score, clock, statistics, and phase for any live match in Sportrix Data.

`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 matches that are live or upcoming for a league (`NOT_STARTED`, `STARTED`, or `CLOSE_OF_PLAY`).
* `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

```bash theme={null}
curl "https://api.sportrixdata.com/api/matches/41282/live" \
  -H "X-API-Key: $KEY"
```

**Example response:**

```json theme={null}
{
  "v": 1,
  "match_id": 41282,
  "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 `/live`                                                   | WebSocket stream                                        |
| ---------------- | -------------------------------------------------------------- | ------------------------------------------------------- |
| **Best for**     | On-demand lookups, polling on a schedule, serverless functions | Continuous real-time display, low-latency score tickers |
| **Scope needed** | `live_scores` or `live_scores_statistics`                      | `live_scores_statistics` only                           |
| **Connection**   | Stateless HTTP — no persistent connection                      | Persistent WebSocket connection                         |
| **Updates**      | You control when you fetch                                     | Server pushes every change as it happens                |

<Tip>
  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`.
</Tip>

## 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).

<Note>
  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`.
</Note>