Sportrix Data Live Snapshot Object — Schema Reference

The live snapshot is the 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 consistent within a sport.

The snapshot schema depends on the sport. Always branch on the sport field. This page documents the soccer snapshot first, then the cricket snapshot (which has a completely different shape — no clock, phase, stats, or events; instead an innings score, batting/bowling cards, a current-over ticker, and a per-innings scorecard). Other sports will follow over time; treat unknown fields as optional.

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

The soccer live snapshot object

Returned with "sport": "soccer".

Top-level fields

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.

Show Provider fields

stat_id

string

Upstream statistics topic id. Always present.

live_id

string

Upstream live id (optional).

fixture_id

string

Upstream fixture id (optional).

sport

string

required

"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

Show Clock fields

minute

integer

Current match minute.

second

integer

Current second within the minute.

period

string

Current period: 1H, 2H, HT, or FT.

running

boolean

true while the clock is ticking; false during breaks (half-time, full-time).

added

integer

Stoppage or added minutes, when applicable.

as_of

datetime

UTC ISO 8601 wall time that minute:second corresponds to — the moment of the last provider frame that updated the clock. Used to project the clock forward between frames. Omitted when there is no anchor (e.g. before kickoff).

Displaying a live timer

minute:second is the clock as of as_of, not as of right now. How you turn it into a ticking timer depends on which surface you read from:

REST (GET /matches/{id}/live) — the server projects the clock forward to request time before responding. When running is true, minute:second is already current and as_of is set to the response time. Display minute:second as-is.
WebSocket snapshot and update frames — frames carry the clock as of the last provider update, so consumers must advance it themselves between frames. While running is true:
```
displayed_seconds = (minute * 60 + second) + (now − as_of)
```
When running is false (half-time, full-time, stoppages), do not project — display minute:second as-is. A new frame will reset the anchor when play resumes.

The clock only ticks within the current period; period transitions (e.g. 1H → HT → 2H) always arrive in a real frame, so the projected value can run uncapped through stoppage time and snaps back if the provider pauses silently.

Phase

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

Show Phase fields

team

string

Which team the phase involves: "home", "away", or an empty string.

code

string

Decoded state code.

label

string

Human-readable label, e.g. "Dangerous attack", "Corner", "Goal", "Safe possession".

string

Raw provider game-state code. Clients can usually ignore this.

Full soccer 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, "as_of": "2026-06-18T02:56:50Z"},
  "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"
}

The cricket live snapshot object

Returned with "sport": "cricket" from the same surfaces as the soccer snapshot — GET /matches/{id}/live and the WebSocket data field. The shape is different: an innings score, the batting and bowling cards, a current-over ticker, the last decoded incident, and a full per-innings scorecard. There is no clock, phase, stats, events, or ball.

Reading a cricket snapshot

The payload has two layers — a quick-glance live state and the full card:

Live, at a glance (top level): score (the current innings total), over (the over in progress), batsmen (the two at the crease), bowler (current spell), and last_event. This is everything you need for a compact live scoreboard — e.g. “West Indies 138/3 (40.1) — Jangoo 20*, Da Silva 12* — Dinusha 9-0-25-1”.
Full detail (scorecard): every innings of the match in order, each with its complete batting and bowling cards, fall of wickets, and an over-by-over breakdown (overs: runs in that over plus cumulative score — the data behind a worm or run-rate graph). Use this for a full scorecard view.

The top-level score/batsmen/bowler/over describe the same innings that is flagged "live": true in scorecard. They come from two separate provider feeds, so they can differ by a ball or two for a moment; the next frame reconciles them. scorecard is omitted until the match is live mid-session — limited-overs games have up to two innings, a Test up to four.

Multi-day Tests. Between days a Test is at stumps: the live snapshot freezes at the last ball — no new frames until play resumes the next day — and the catalog match object’s status becomes CLOSE_OF_PLAY (see Match status values), so the match stays visible in /matches and /matches/live rather than disappearing overnight. The snapshot’s own status (below) is the in-play state and is distinct from that catalog lifecycle status.

Top-level fields

match_id

integer

Your match id. Present on WebSocket frames.

sport

string

required

"cricket".

competition

string

required

Competition or match name, e.g. "West Indies vs Sri Lanka - 1st Test".

home

string

required

Home team name.

away

string

required

Away team name.

status

string

required

Current match state: not_started, live, innings_break, stopped (rain, bad light, tea, …), or ended.

match_type

string

required

Format: test, t20, one_day (50-over), the_hundred, or limited_overs (overs not yet known).

innings

integer

required

Current innings number.

batting

string

required

Side at the crease: "home" or "away".

score

object

required

The batting side’s innings score. See Cricket score below.

set_score

string

Raw score string from the provider; for a multi-innings match it may carry prior innings too.

over

object

required

Current-over ticker. See Over below.

batsmen

array

required

The two batters at the crease. See Batsman below.

bowler

object

required

Current bowler’s spell figures. See Bowler below.

last_event

object

The decoded last incident. See Last event below.

scorecard

array

Full per-innings card (all innings, in order). See Scorecard below. Omitted until the match is live mid-session.

datetime

required

When this snapshot was produced, in ISO 8601 UTC.

Cricket score

The batting side’s current innings total.

Show Score fields

runs

integer

Runs scored.

wickets

integer

Wickets fallen.

overs

string

Overs faced, e.g. "62.1".

raw

string

Raw score string, e.g. "262/6".

Over

Ticker for the over in progress.

Show Over fields

over

integer

Over in progress (1-based).

ball

integer

Ball within the over.

this_over

array

The deliveries bowled in this over so far (runs as strings, "W" for a wicket, etc.).

Batsman

Each entry in batsmen describes one of the two batters at the crease.

Show Batsman fields

name

string

Batter name.

runs

integer

Runs scored in this innings.

balls

integer

Balls faced in this innings.

on_strike

boolean

true for the batter on strike. Omitted on the non-striker.

Bowler

The current bowler’s spell figures.

Show Bowler fields

name

string

Bowler name.

overs

string

Overs bowled this spell.

maidens

integer

Maiden overs.

runs

integer

Runs conceded.

wickets

integer

Wickets taken.

Scorecard

scorecard is an array of innings — every innings of the match, in order. The live innings is flagged with "live": true; finished innings carry their final figures; innings yet to bat are present but omit score.

Show Innings fields

team

string

Batting team, e.g. "West Indies".

phase

string

1st or 2nd (this team’s innings number).

score

string

Innings score, e.g. "138/3". Omitted for an innings yet to bat.

live

boolean

true for the innings in progress. Omitted otherwise.

batting

array

Batting card — one row per batter. Each row has name, dismissal ("c X b Y", "not out", …), runs, balls, fours, sixes, and strike_rate.

bowling

array

Bowling card — one row per bowler. Each row has name, overs, maidens, runs, wickets, and economy.

fall_of_wickets

array

Wickets in the order they fell: { "wicket": int, "score": int, "batsman": string }.

overs

array

Per-over breakdown: { "over": int, "runs": int, "score": string } — runs is the runs in that over, score the cumulative innings score after it. Drives a worm or run-rate graph.

extras

integer

Total extras for the innings. Omitted if none.

extras_detail

string

Extras breakdown, e.g. "b 16,lb 1,w 1,nb 2,P 0".

Last event

The decoded last incident on the field.

Show Last event fields

string

Raw provider code.

team

string

"home", "away", or an empty string.

code

string

Decoded code.

label

string

Human-readable label, e.g. runs, wicket, bowled, LBW, caught, bowling, century, end of over.

Full cricket example

{
  "match_id": 41822,
  "sport": "cricket",
  "competition": "West Indies vs Sri Lanka - 1st Test",
  "home": "West Indies",
  "away": "Sri Lanka",
  "status": "live",
  "match_type": "test",
  "innings": 2,
  "batting": "home",
  "score": {"runs": 138, "wickets": 3, "overs": "40.1", "raw": "138/3"},
  "set_score": "138/3",
  "over": {"over": 41, "ball": 1, "this_over": ["1"]},
  "batsmen": [
    {"name": "AA Jangoo", "runs": 20, "balls": 46, "on_strike": true},
    {"name": "J Da Silva", "runs": 12, "balls": 36}
  ],
  "bowler": {"name": "GS Dinusha", "overs": "9.0", "maidens": 0, "runs": 25, "wickets": 1},
  "last_event": {"vc": "21206", "team": "away", "code": "1206", "label": "bowling"},
  "scorecard": [
    {
      "team": "Sri Lanka", "phase": "1st", "score": "308",
      "batting": [
        {"name": "N Madushka", "dismissal": "c Da Silva b Seales", "runs": 84, "balls": 142, "fours": 9, "sixes": 1, "strike_rate": "59"}
      ],
      "bowling": [
        {"name": "JNT Seales", "overs": "22.0", "maidens": 5, "runs": 71, "wickets": 4, "economy": "3.23"}
      ],
      "fall_of_wickets": [
        {"wicket": 10, "score": 308, "batsman": "CAK Rajitha"}
      ],
      "extras": 17, "extras_detail": "b 4,lb 9,w 2,nb 2,P 0"
    },
    {
      "team": "West Indies", "phase": "1st", "score": "138/3", "live": true,
      "batting": [
        {"name": "JD Campbell", "dismissal": "c N Madushka b GS Dinusha", "runs": 39, "balls": 64, "fours": 3, "sixes": 2, "strike_rate": "61"},
        {"name": "AA Jangoo", "dismissal": "not out", "runs": 20, "balls": 46, "fours": 3, "sixes": 0, "strike_rate": "43"}
      ],
      "bowling": [
        {"name": "RMMP Rathnayaka", "overs": "11.0", "maidens": 2, "runs": 30, "wickets": 2, "economy": "2.73"}
      ],
      "fall_of_wickets": [
        {"wicket": 1, "score": 58, "batsman": "BA King"},
        {"wicket": 2, "score": 97, "batsman": "JD Campbell"}
      ],
      "overs": [
        {"over": 1, "runs": 0, "score": "0/0"},
        {"over": 2, "runs": 12, "score": "12/0"}
      ],
      "extras": 20, "extras_detail": "b 16,lb 1,w 1,nb 2,P 0"
    }
  ],
  "t": "2026-06-25T11:30:00Z"
}

The batting and bowling arrays above are trimmed to one or two rows for brevity; a real innings carries every batter and bowler.

Appendix: enumerations

Snapshot sport: soccer, cricket. Other sports may appear in future — branch on this field. Snapshot status — soccer: not_started, live, ht, ft. Snapshot status — cricket: not_started, live, innings_break, stopped (rain, bad light, tea, …), ended. Cricket match_type: test, t20, one_day (50-over), the_hundred, limited_overs (overs not yet known). Clock period (soccer): 1H, 2H, HT, FT (and similar period codes). Event type (soccer): goal, corner, yellow_card, red_card, penalty, substitution, event. Common soccer stat keys: shots_on_target, shots_off_target, attacks, dangerous_attacks, possession, corners, yellow_cards, red_cards. Cricket last_event.label is drawn from the provider’s incident table, e.g. runs, bye, wide, no ball, wicket, bowled, LBW, caught, stumped, run out, bowling, maiden over, end of over, duck, century, review, innings break, match ended. Catalog match status (for the match object, not the live snapshot): NOT_STARTED, STARTED, CLOSE_OF_PLAY (multi-day cricket Test between days), FINISHED.

​Used by

​The soccer live snapshot object

​Top-level fields

​Clock

​Displaying a live timer

​Phase

​Full soccer example

​The cricket live snapshot object

​Reading a cricket snapshot

​Top-level fields

​Cricket score

​Over

​Batsman

​Bowler

​Scorecard

​Last event

​Full cricket example

​Appendix: enumerations

Used by

The soccer live snapshot object

Top-level fields

Clock

Displaying a live timer

Phase

Full soccer example

The cricket live snapshot object

Reading a cricket snapshot

Top-level fields

Cricket score

Over

Batsman

Bowler

Scorecard

Last event

Full cricket example

Appendix: enumerations