matches

List matches with filters

Filter the scheduled and recent match list. Both ?sport= and ?league= are optional: a bare /v1/matches returns upcoming matches across all sports. data is ALWAYS an array of match objects, for every sport and every league. ?league=nba is the one NBA history surface and reaches all 80 archive seasons plus canonical match-only rows. Its shape is an additive superset: archive identity/statistics and time_precision are added. Where only a date is genuinely known, kickoff_utc is that date at midnight UTC and time_precision=date; the time is not a tip-off. For the live per-adapter scores feed (integer scores keyed by match_id) use /v1/scores with the same parameters. ?date accepts an ISO date (YYYY-MM-DD) or the literal 'today'.

get/v1/matches

Request

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

Query parameters

sport'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football'
leaguestring

A short league code, not an id. GET /v1/leagues returns the authoritative list in its id field; that is the value to pass to every ?league= parameter. Some codes accept an alias (serie_a and seriea both resolve).

Example:epl

Required for multi-league sports (e.g. football). League code such as epl, laliga, bundesliga, serie_a, ligue1, cl, mls.

datestring

ISO date (YYYY-MM-DD) or the literal 'today' (the current UTC date). Selects a UTC calendar day: kickoffs at or after 00:00Z on that date and before 00:00Z the next day. An evening game in the Americas often kicks off after 00:00Z and is listed under the NEXT date. Responses served from stored matches echo the exact window applied in meta.date_window.

tzstring
Example:America/New_York

Optional IANA time zone name (e.g. America/New_York). ?date= and ?date=today then select the local calendar day in that zone, bounded by local midnights converted to UTC (23 or 25 hours on a clock-change day). Offsets such as -05:00 are rejected with 400. Omit for UTC. Example: ?league=nfl&date=2026-09-13&tz=America/New_York.

status'scheduled' | 'live' | 'in_progress' | 'finished' | 'postponed' | 'cancelled' | 'suspended'
seasoninteger

Season start year. With ?league=nba, 2025 means the 2025-26 campaign.

teamstring

NBA only: canonical team UUID, archive team ID, or abbreviation.

type'REG' | 'POST' | 'PRE' | 'ALLSTAR' | 'Regular Season' | 'Playoffs' | 'Pre Season' | 'All Star'

NBA only: season segment.

limitinteger
offsetinteger

Response

ok

Example response

{
  "data": [
    {
      "id": "cf2d81c8-8e7c-4eaf-a515-c51be3962e57",
      "league": "MLB",
      "home": {
        "id": "cf2d81c8-8e7c-4eaf-a515-c51be3962e57"
      },
      "away": {
        "id": "cf2d81c8-8e7c-4eaf-a515-c51be3962e57"
      },
      "round": "Regular Season - 2"
    }
  ],
  "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 2 revisions of this API.