Cricket live match state
Current innings state for one cricket match (overs bowled, runs, wickets, target and run rates), read from cricket_match_state, which the hourly cricket ingest appends to ONLY while a match is in progress.
meta.available is false, and data.state null, whenever no snapshot was ever recorded: a scheduled match, a match between innings before the first hourly capture, or any match that finished before this write path was wired (2026-08-12). That is the common answer and it is never padded with a zeroed-out innings.
meta.live describes the PAYLOAD, not the match: true only when the match is in progress AND a snapshot exists. For a finished match the last recorded snapshot is returned with live: false and a note, so a closing reading is never mistaken for a current one. recorded_at carries the observation time in every case.
required_run_rate is present only where it can be computed honestly (T20-format chases); it is omitted for ODIs and Tests rather than derived from an assumed innings length.
Request
- Base URL: https://api.bigballsdata.com
- URL: https://api.bigballsdata.com/v1/cricket/matches/{id}/state
- Auth: one of:
- API key in header x-api-key
- HTTP bearer
Path parameters
A stored BigBalls id. This is the identifier every match, team, player and league endpoint returns, and the one every {id} path segment accepts. Take it from the id field of the corresponding list endpoint and use it as-is.
Query parameters
Return the newest snapshot for THIS innings instead of the newest snapshot for the match. cricket_match_state is append-only and per-innings, so a multi-innings match holds state for each innings it was captured during; without this parameter only the last one is reachable. Ordering within the innings is recorded_at DESC, id DESC, the same tiebreak the unfiltered default uses, narrowed rather than replaced.
Omit it for the previous behaviour, which is unchanged: newest snapshot for the match, and a 200 with data.state: null / meta.available: false when none exists.
An innings with no snapshot is a 404, not a 200 with available: false. You asked a specific question, and the empty 200 cannot distinguish "this match has no state at all" from "we hold innings 1 and 3, not 7". The 404 names the innings we do hold in meta.available_innings and in suggested_fix. A non-integer or non-positive value (?innings=abc, ?innings=0) is a 400.
Response
ok. data.state is null when no state was recorded (still 200); this is the no-parameter case. meta.filters_applied.innings echoes the innings actually applied, or null when none was requested.
Example response
{
"data": {
"state": {
"innings_number": 2,
"overs_bowled": 12,
"runs_scored": 88,
"wickets_fallen": 3,
"current_run_rate": 7.33,
"target": 161,
"required_run_rate": 9.13,
"result_method": "DLS"
}
},
"meta": {
"date_window": {
"timezone": "UTC",
"start_utc": "2026-09-13T00:00:00.000Z",
"end_utc": "2026-09-14T00:00:00.000Z"
},
"source": "official-league",
"confidence": 0.95,
"cache_age_ms": 4200,
"request_id": "req_abc123",
"note": "match_id is omitted on 380 of 380 rows in this response. The live feed behind them does not carry an id we can resolve to a stored match, so we return no id rather than one that will not work. For rows with ids you can call back into, use /v1/stored/matches with the same sport or league, for example /v1/stored/matches?league=epl."
},
"error": {
"code": "NOT_FOUND"
}
}Changes
No recorded changes to this operation across all 3 revisions of this API.