cricket

List cricket matches

Cricket match list, served from stored rows. Returns a JSON ARRAY in data, never a {scores: ...} object. Narrow with ?series= (matched case-insensitively as a substring of the competition name) and ?date= (one day, or an inclusive START:END range of days), and page with ?limit= + ?offset=.

get/v1/cricket/matches

Request

  • Base URL: https://api.bigballsdata.com
  • URL: https://api.bigballsdata.com/v1/cricket/matches
  • Auth: one of:
    • API key in header x-api-key
    • HTTP bearer

Query parameters

seriesstring

Competition name or fragment, matched case-insensitively against the league name.

datestring
Example:2026-09-10:2026-09-24

Filters on the match's KICKOFF instant. Two spellings, the same grammar as ?date= on /v1/games: (a) YYYY-MM-DD, one UTC calendar day: kickoff at or after 00:00Z that date and before 00:00Z the next. (b) START:END, an INCLUSIVE range of calendar days, so 2026-09-10:2026-09-24 covers the whole of the 24th, from 00:00Z on the 10th up to (but not including) 00:00Z on the 25th. START must be on or before END; a backwards range is a 400, not an empty 200. There is no cap on the span; this endpoint is paged, so ?limit= and ?total bound the response. Multi-day formats (a four-day County Championship match) are matched on their kickoff day ALONE: a match that starts on the 9th and runs into the 11th does NOT appear under ?date=2026-09-10:2026-09-24. The exact half-open instant window applied is echoed in meta.date_window, so the bucketing is never something you have to infer.

tzstring
Example:America/New_York

Optional IANA time zone name (e.g. Asia/Kolkata). ?date= then selects local calendar days in that zone, both ends, instead of UTC ones. Offsets such as +05:30 are rejected with 400. Example: ?date=2026-09-10:2026-09-24&tz=Asia/Kolkata.

limitinteger

Page size.

offsetinteger

Rows to skip. Results are ordered by kickoff descending with a unique tiebreak, so pages are stable across requests.

pageinteger

Alias for ?offset=(page-1)*limit. An explicit ?offset= wins.

status'scheduled' | 'live' | 'finished' | 'postponed' | 'cancelled'

NOT a supported filter on this endpoint; sending it returns 400 rather than being accepted and ignored.

Response

ok. data is an array of matches (empty when the filter genuinely matches nothing). meta carries count (rows in this page), total (rows matching the filter), limit and offset.

dataobject[] required

Example response

{
  "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.