SportriX 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 sportdata 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

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 1Schema version. Currently 1.

integer

Your match id. Present on WebSocket frames for multiplexing; omitted on REST responsesYour match id. Present on WebSocket frames for multiplexing; omitted on REST responses.

object

Upstream reference ids. Clients can usually ignore this objectUpstream reference ids. Clients can usually ignore this object.

Show Provider fields

string

Upstream statistics topic id. Always present.

string

Upstream live id (optional).

string

Upstream fixture id (optional).

Show Provider fields

string

Upstream statistics topic id. Always present.

string

Upstream live id (optional).

string

Upstream fixture id (optional).

string

required

"soccer""soccer".

string

required

League or competition name, e.g. "USA MLS Next Pro League"League or competition name, e.g. "USA MLS Next Pro League".

string

required

Home team nameHome team name.

string

required

Away team nameAway team name.

string

required

Current match state: live, ht (half-time), ft (full-time), or not_startedCurrent match state: live, ht (half-time), ft (full-time), or not_started.

object

required

Match clock. See Clock belowtch clock. See Clock below.

object

required

Current score. See Score belowCurrent score. See Score below.

object

required

Decoded current game state. See Phase belowDecoded current game state. See Phase below.

object

required

Map of stat key → {"home": int, "away": int}. See StatisticsMap of stat key → {"home": int, "away": int}. See Statistics.

array | null

Timeline incidents. null if no events have occurred yet. See Events.

object

Last event-anchored ball position on the pitch. See Ball Position.

datetime

required

When this snapshot was produced, in ISO 8601 UTC.

array | null

Timeline incidents. null if no events have occurred yet. See Events.

object

Last event-anchored ball position on the pitch. See Ball Position.

datetime

required

When this snapshot was produced, in ISO 8601 UTC.

ScorScore

The current match score as {"home": int, "away": int}, with an optional shootout tally when a penalty shootout has beguncurrent match score as {"home": int, "away": int}, with an optional shootout tally when a penalty shootout has begun.

Show Score fields

integer

required

Home team goalsHome team goals.

integer

required

Away team goalsAway team goals.

object

Per-side penalty-shootout tally as {"home": int, "away": int}. Present only once a shootout has begun. home and away above remain at the post-extra-time result, so shootout is the only field that reveals the shootout winner — compare shootout.home and shootout.away to determine which side advancesPer-side penalty-shootout tally as {"home": int, "away": int}. Present only once a shootout has begun. home and away above remain at the post-extra-time result, so shootout is the only field that reveals the shootout winner — compare shootout.home and shootout.away to determine which side advances.

"score": {"home": 1, "away": 1, "shootout": {"home": 4, "away": 3}}

Clock

Show Clock fields

integer

Current match minute.

integer

Current second within the minute.

string

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

boolean

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

integer

Stoppage or added minutes, when applicable.

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

string

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

string

Decoded state code.

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

integer

Your match id. Present on WebSocket frames.

string

required

"cricket".

string

required

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

string

required

Home team name.

string

required

Away team name.

string

required

Current match state: live, ht (half-time), et (extra time in progress), shootout (penalty shootout in progress), ft (full-time — used for both regulation full-time and after extra time), or not_started.Current match state: live, ht (half-time), et (extra time in progress), shootout (penalty shootout in progress), ft (full-time — used for both regulation full-time and after extra time), or not_started.Current match state: not_started, live, innings_break, stopped (rain, bad light, tea, …), or ended.

string

required

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

integer

required

Current innings number.

string

required

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

object

required

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

string

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

object

required

Current-over ticker. See Over below.

array

required

The two batters at the crease. See Batsman below.

object

required

Current bowler’s spell figures. See Bowler below.

object

The decoded last incident. See Last event below.

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

integer

Runs scored.

integer

Wickets fallen.

string

Overs faced, e.g. "62.1".

string

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

Over

Ticker for the over in progress.

Show Over fields

integer

Over in progress (1-based).

integer

Ball within the 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

string

Batter name.

integer

Runs scored in this innings.

integer

Balls faced in this innings.

boolean

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

Bowler

The current bowler’s spell figures.

Show Bowler fields

string

Bowler name.

string

Overs bowled this spell.

integer

Maiden overs.

integer

Runs conceded.

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

string

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

string

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

string

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

boolean

true for the innings in progress. Omitted otherwise.

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.

array

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

array

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

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.

integer

Total extras for the innings. Omitted if none.

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.

string

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

string

Decoded code.

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, shootout, 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.

"score": {"home": 1, "away": 1, "shootout": {"home": 4, "away": 3}}

Clock

Show Clock fields

integer

Current match minute.

integer

Current second within the minute.

string

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

boolean

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

integer

Stoppage or added minutes, when applicable.

datetime

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.

Phase

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

Show Phase fields

string

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

string

Decoded state code.

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

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.

Top-level fields

integer

Your match id. Present on WebSocket frames.

string

required

"cricket".

string

required

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

string

required

Home team name.

string

required

Away team name.

string

required

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

string

required

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

integer

required

Current innings number.

string

required

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

object

required

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

string

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

object

required

Current-over ticker. See Over below.

object

required

Map of stat key → {"home": int, "away": int} (integer counters). See StatisticsMap of stat key → {"home": int, "away": int} (integer counters). See Statistics.

object

Expected goals per side, {"home": float, "away": float}. Optional — omitted when the provider doesn’t supply it (common in smaller leagues)Expected goals per side, {"home": float, "away": float}. Optional — omitted when the provider doesn’t supply it (common in smaller leagues).

object

Fractional stats map — same shape as stats but with float values, for stats that are naturally percentages or ratios (e.g. passing_accuracy, crossing_accuracy in 0–1; action_area as an attacking-third share). Optional. See StatisticsFractional stats map — same shape as stats but with float values, for stats that are naturally percentages or ratios (e.g. passing_accuracy, crossing_accuracy in 0–1; action_area as an attacking-third share). Optional. See Statistics.

array

Per-minute pressure series — an array of floats in [-1, 1], oldest first. Positive values mean the home side is pressing, negative values the away side. OptionalPer-minute pressure series — an array of floats in [-1, 1], oldest first. Positive values mean the home side is pressing, negative values the away side. Optional.

object

Each team’s recent results coming into this match, as {"home": [...], "away": [...]}. See Form below. OptionalEach team’s recent results coming into this match, as {"home": [...], "away": [...]}. See Form below. Optional.

array

required

The two batters at the crease. See Batsman below.

object

required

Current bowler’s spell figures. See Bowler below.

array

Chronological list of goalscorers. See Goals below. Optional.

array

10-minute incident buckets, oldest first. See Intervals below. Optional.

array

Per-player match tallies (shots, assists, saves, …). See Players below. Optional.

object

The decoded last incident. See Last event below.

object

Ball position on the pitch. While a live animation position is streaming, ball follows it (only x/y/event set); otherwise it anchors to the last notable event (goal, shot, …) with detail and minute filled. See Ball Position.

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.

Fields marked optional above are omitted when the provider doesn’t supply them — smaller leagues often lack xg, momentum, and players. Guard for their presence rather than assuming they’re always set.

Cricket score

array

required

The two batters at the crease. See Batsman below.

object

required

Current bowler’s spell figures. See Bowler below.

array

Chronological list of goalscorers. See Goals below. Optional.

array

10-minute incident buckets, oldest first. See Intervals below. Optional.

array

Per-player match tallies (shots, assists, saves, …). See Players below. Optional.

object

The decoded last incident. See Last event below.

object

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

Show Clock fields

integer

Current match minutCurrent match minute.

integer

Current second within the minuteCurrent second within the minute.

string

Current period: 1H, 2H, HT, FT. For matches that go past 90 minutes: ET1 / ET2 (extra-time halves, running), ET (the break between them), AET (full time after extra time), and SO (penalty shootout)Current period: 1H, 2H, HT, FT. For matches that go past 90 minutes: ET1 / ET2 (extra-time halves, running), ET (the break between them), AET (full time after extra time), and SO (penalty shootout).

boolean

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

integer

Added / stoppage minutes for the current period. While the referee’s board is up, this is that live announcement (e.g. 4 for “+4”); once the announced window has elapsed, it holds the minutes actually played overAdded / stoppage minutes for the current period. While the referee’s board is up, this is that live announcement (e.g. 4 for “+4”); once the announced window has elapsed, it holds the minutes actually played over.

datetime

The batting side’s current innings total.

Show Score fields

integer

Runs scored.

integer

Wickets fallen.

string

Overs faced, e.g. "62.1".

string

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

Over

Ticker for the over in progress.

Show Over fields

integer

Over in progress (1-based).

integer

Ball within the 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

string

Batter name.

integer

Runs scored in this innings.

integer

Balls faced in this innings.

boolean

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

Bowler

The current bowler’s spell figures.

Show Bowler fields

string

Bowler name.

string

Overs bowled this spell.

integer

Maiden overs.

integer

Runs conceded.

integer

Wickets taken.

Scorecard

Show Innings fields

string

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

string

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

string

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

boolean

true for the innings in progress. Omitted otherwise.

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.

array

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

array

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

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.

integer

Total extras for the innings. Omitted if none.

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.

string

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

string

Decoded code.

string

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

Show Phase fields

string

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

string

Decoded state code.

string

Human-readable label, e.g. "Dangerous attack", "Corner", "Goal", "Safe possession", "Half time", "End of extra time", "VAR - reviewing goal".

string

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

Match against code, not label. Labels are display text and may be refined over time — for example, codes that used to read "General alert" now carry their specific meaning — so any client logic that depends on the phase should key off the stable code.

Form

form decodes each team’s last matches coming into this one. Each entry describes one previous fixture, most recent first.

Show Form entry fields

string

W, D, or L from the perspective of the team.

string

H (home), A (away), or N (neutral).

string

Final score as "<for>:<against>", e.g. "2:0".

string

Opponent name. May be empty when the provider doesn’t supply it.

"form": {
  "home": [{"result": "W", "venue": "N", "score": "2:0", "opponent": "Ghana"}],
  "away": []
}

Goals

Each entry in goals is one scorer, in chronological order. This is the goalscorer list you’d render alongside the match score; the events array carries every incident, goals is the pre-filtered subset.

Show Goal fields

string

"home" or "away".

string

Scorer in short display form, e.g. "L Romo".

string

Match minute, e.g. "60" or "120+5".

string

How the goal was scored: "Shot", "Header", "Penalty", and similar. Optional.

number

Shot origin x on a normalized 0–1 pitch (optional).

number

Shot origin y on a normalized 0–1 pitch (optional).

Intervals

Each entry in intervals is one 10-minute bucket of incident counts, oldest first. Buckets have a fixed per-side shape, so summing across buckets reconciles with the match counters in stats. Use this for a “shots by phase of match” or interval-based betting view without post-processing the events timeline yourself.

Show Interval fields

string

The bucket window, e.g. "00:00-09:59", "10:00-19:59". The last regulation bucket is "80:00-End"; extra-time buckets follow when played.

object

Per-side counts for the home team: goals, corners, yellow_cards, red_cards, throw_ins, free_kicks, goal_kicks, substitutions, penalties.

object

Same shape as home, for the away team.

Players

Each entry in players is one player’s cumulative match tallies — the data behind a per-player markets view (shots, cards, assists).

Show Player fields

string

Stable provider player id.

string

Display name.

object

Map of stat key → integer. Common keys: shots, shots_on_target, assists, bookings, saves (goalkeepers), fouls, fouled, touches. Open-ended — iterate keys rather than assuming a fixed set.

Full cricket 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": 4, "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},
    "keeper_saves": {"home": 1, "away": 2}
  },
  "xg": {"home": 1.48, "away": 0.42},
  "stats_float": {"passing_accuracy": {"home": 0.9, "away": 0.63}},
  "momentum": [-0.99, -0.97, -0.28, 0.13],
  "form": {
    "home": [{"result": "W", "venue": "N", "score": "2:0", "opponent": "Ghana"}],
    "away": []
  },
  "events": [
    {"minute": "60", "type": "goal", "team": "home", "label": "Goal", "score": "1-0", "player": "Luis Romo", "important": true, "replay": "3yn3afp4xbimp9uj01w4lmcgy"}
  ],
  "goals": [
    {"team": "home", "player": "L Romo", "minute": "60", "method": "Shot", "x": 0.9, "y": 0.46}
  ],
  "intervals": [
    {
      "window": "00:00-09:59",
      "home": {"goals": 0, "corners": 1, "yellow_cards": 0, "red_cards": 0, "throw_ins": 1, "free_kicks": 0, "goal_kicks": 1, "substitutions": 0, "penalties": 0},
      "away": {"goals": 0, "corners": 0, "yellow_cards": 0, "red_cards": 0, "throw_ins": 0, "free_kicks": 2, "goal_kicks": 2, "substitutions": 0, "penalties": 0}
    }
  ],
  "players": [
    {"id": "693705", "name": "Youri Tielemans", "stats": {"shots": 4, "shots_on_target": 2}}
  ],
  "ball": {"x": 0.91, "y": 0.5, "event": "goal", "minute": "60"},
  "updated_at": "2026-06-18T02:56:50Z"
}

{
  "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. The batting side’s current innings total.

Show Score fields

integer

Runs scored.

integer

Wickets fallen.

string

Overs faced, e.g. "62.1".

string

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

Over

Ticker for the over in progress.

Show Over fields

integer

Over in progress (1-based).

integer

Ball within the 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

string

Batter name.

integer

Runs scored in this innings.

integer

Balls faced in this innings.

boolean

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

Bowler

The current bowler’s spell figures.

Show Bowler fields

string

Bowler name.

string

Overs bowled this spell.

integer

Maiden overs.

integer

Runs conceded.

integer

Wickets taken.

Scorecard

Show Innings fields

string

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

string

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

string

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

boolean

true for the innings in progress. Omitted otherwise.

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.

array

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

array

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

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.

integer

Total extras for the innings. Omitted if none.

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.

string

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

string

Decoded code.

string

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

Show Phase fields

string

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

string

Decoded state code.

string

Human-readable label, e.g. "Dangerous attack", "Corner", "Goal", "Safe possession", "Half time", "End of extra time", "VAR - reviewing goal".

string

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

Form

form decodes each team’s last matches coming into this one. Each entry describes one previous fixture, most recent first.

Show Form entry fields

string

W, D, or L from the perspective of the team.

string

H (home), A (away), or N (neutral).

string

Final score as "<for>:<against>", e.g. "2:0".

string

Opponent name. May be empty when the provider doesn’t supply it.

"form": {
  "home": [{"result": "W", "venue": "N", "score": "2:0", "opponent": "Ghana"}],
  "away": []
}

Goals

Show Goal fields

string

"home" or "away".

string

Scorer in short display form, e.g. "L Romo".

string

Match minute, e.g. "60" or "120+5".

string

How the goal was scored: "Shot", "Header", "Penalty", and similar. Optional.

number

Shot origin x on a normalized 0–1 pitch (optional).

number

Shot origin y on a normalized 0–1 pitch (optional).

Intervals

Show Interval fields

string

The bucket window, e.g. "00:00-09:59", "10:00-19:59". The last regulation bucket is "80:00-End"; extra-time buckets follow when played.

object

Per-side counts for the home team: goals, corners, yellow_cards, red_cards, throw_ins, free_kicks, goal_kicks, substitutions, penalties.

object

Same shape as home, for the away team.

Players

Each entry in players is one player’s cumulative match tallies — the data behind a per-player markets view (shots, cards, assists).

Show Player fields

string

Stable provider player id.

string

Display name.

object

Full cricket 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": 4, "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},
    "keeper_saves": {"home": 1, "away": 2}
  },
  "xg": {"home": 1.48, "away": 0.42},
  "stats_float": {"passing_accuracy": {"home": 0.9, "away": 0.63}},
  "momentum": [-0.99, -0.97, -0.28, 0.13],
  "form": {
    "home": [{"result": "W", "venue": "N", "score": "2:0", "opponent": "Ghana"}],
    "away": []
  },
  "events": [
    {"minute": "60", "type": "goal", "team": "home", "label": "Goal", "score": "1-0", "player": "Luis Romo", "important": true, "replay": "3yn3afp4xbimp9uj01w4lmcgy"}
  ],
  "goals": [
    {"team": "home", "player": "L Romo", "minute": "60", "method": "Shot", "x": 0.9, "y": 0.46}
  ],
  "intervals": [
    {
      "window": "00:00-09:59",
      "home": {"goals": 0, "corners": 1, "yellow_cards": 0, "red_cards": 0, "throw_ins": 1, "free_kicks": 0, "goal_kicks": 1, "substitutions": 0, "penalties": 0},
      "away": {"goals": 0, "corners": 0, "yellow_cards": 0, "red_cards": 0, "throw_ins": 0, "free_kicks": 2, "goal_kicks": 2, "substitutions": 0, "penalties": 0}
    }
  ],
  "players": [
    {"id": "693705", "name": "Youri Tielemans", "stats": {"shots": 4, "shots_on_target": 2}}
  ],
  "ball": {"x": 0.91, "y": 0.5, "event": "goal", "minute": "60"},
  "updated_at": "2026-06-18T02:56:50Z"
}

{
  "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, et (extra time), shootout, ft (regulation or after extra time)tatus — soccer: not_started, live, ht, et (extra time), shootout, ft (regulation or after extra time). Snapshot status — cricket: not_started, live, innings_break, stopped (rain, bad light, tea, …), endedcricket: 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)Cricket match_type: test, t20, one_day (50-over), the_hundred, limited_overs (overs not yet known). Clock period (soccer): 1H, 2H, HT, FT, ET1, ET2 (extra-time halves), ET (break between them), AET (full time after extra time), SO (penalty shootoutlock period (soccer): 1H, 2H, HT, FT, ET1, ET2 (extra-time halves), ET (break between them), AET (full time after extra time), SO (penalty shootout). Event type (soccer): goal, corner, yellow_card, red_card, penalty, substitution, shot_on_target, shot_off_target, offside, assist, period_score (HT/FT/AET score markers), shootout (penalty-shootout kicks), event. Treat unknown types as eventEvent type (soccer): goal, corner, yellow_card, red_card, penalty, substitution, shot_on_target, shot_off_target, offside, assist, period_score (HT/FT/AET score markers), shootout (penalty-shootout kicks), event. Treat unknown types as event. Common soccer stat keys (integer counters in stats): shots_on_target, shots_off_target, attacks, dangerous_attacks, possession (percentage), corners, yellow_cards, red_cards, throw_ins, free_kicks, goal_kicks, penalties, substitutions, keeper_saves, key_passes, crossesCommon soccer stat keys (integer counters in stats): shots_on_target, shots_off_target, attacks, dangerous_attacks, possession (percentage), corners, yellow_cards, red_cards, throw_ins, free_kicks, goal_kicks, penalties, substitutions, keeper_saves, key_passes, crosses. Fractional stat keys (float values in stats_float): passing_accuracy, crossing_accuracy (both 0–1), action_area (attacking-third share, %)Fractional stat keys (float values in stats_float): passing_accuracy, crossing_accuracy (both 0–1), action_area (attacking-third share, %). 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.Catalog match status (for the match object, not the live snapshot): NOT_STARTED, STARTED, CLOSE_OF_PLAY (multi-day cricket Test between days), FINISHED.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

​Used by

​The soccer live snapshot object

​Top-level fields

​ScorScore

​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

​Clock

​Displaying a live timer

​Phase

​Full soccer example

​The cricket live snapshot object

​Reading a cricket snapshot

​Top-level fields

​Cricket score

​Cricket score

​Over

​Batsman

​Bowler

​Scorecard

​Last event

​Form

​Goals

​Intervals

​Players

​Full cricket example

​Appendix: enumerations

​Over

​Batsman

​Bowler

​Scorecard

​Last event

​Form

​Goals

​Intervals

​Players

​Full cricket example

​Appendix: enumerations

Used by

The soccer live snapshot object

Top-level fields

Used by

The soccer live snapshot object

Top-level fields

ScorScore

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

Clock

Displaying a live timer

Phase

Full soccer example

The cricket live snapshot object

Reading a cricket snapshot

Top-level fields

Cricket score

Cricket score

Over

Batsman

Bowler

Scorecard

Last event

Form

Goals

Intervals

Players

Full cricket example

Appendix: enumerations

Over

Batsman

Bowler

Scorecard

Last event

Form

Goals

Intervals

Players

Full cricket example

Appendix: enumerations