teams

Team profile + stored record

The team as GET /v1/teams lists it: id, name, short_name, logo_url, flag_url, sport, league, plus a stats object carrying the same aggregate GET /v1/teams/{id}/stats returns. One implementation serves both, so the two cannot disagree.

stats covers every finished match we hold for the team, not the current season. meta.stats_scope says so on each response. The summary read "current season stats" until 2026-09-08; it was never true of the numbers this route or its /stats sibling produced.

A well-formed uuid naming no team is a 404, with or without ?sport=.

?season= does not narrow this route and never did. It used to be forwarded to a live lookup that returned nothing. Passing it now returns meta.ignored_params: ["season"] rather than silently answering a narrower question with a wider number. For season-scoped figures use /v1/teams/{id}/season or /v1/teams/{id}/matches?season=.

get/v1/teams/{id}

Request

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

Path parameters

idstring uuid required

Query parameters

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

Optional. Inferred from the team when absent. Only affects the plan gate.

seasonstring

Accepted but IGNORED. The response discloses it in meta.ignored_params.

Response

ok

Example response

{
  "data": {
    "id": "cf2d81c8-8e7c-4eaf-a515-c51be3962e57",
    "league": "NHL",
    "stats": {
      "form_string": "WLWLL"
    }
  },
  "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.