teams

Matches for a team

Resolves the historical field for one team. Returns the standard Envelope with a FieldMap.

get/v1/teams/{id}/matches

Request

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

Path parameters

idstring uuid required

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.

Example:cf2d81c8-8e7c-4eaf-a515-c51be3962e57

Query parameters

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

Required.

seasonstring

Season LABEL, not a calendar year: the year a season STARTS in. 2025 means the 2025-26 campaign for leagues that cross the new year (EPL, NBA, NHL) and the 2025 season for those that do not (MLB, MLS, WNBA). Filtering resolves each league's own start month, so a season never spans two calendar years' worth of rows.

limitinteger
offsetinteger
pageinteger

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

Response

ok. data.historical is a FieldResult, or null when unavailable (still 200).

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 3 revisions of this API.