--- title: "Team profile + stored record" method: GET path: "/v1/teams/{id}" tags: ["teams"] --- # Team profile + stored record `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 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=`. ## Path parameters - `id` string, uuid, required ## Query parameters - `sport` 'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football' - `season` string ## Response `200` ok - object: The standard response wrapper. Only `data` is guaranteed. `error` is absent (not null) on 16 of 40 live 200 responses measured 2026-09-18, so test for the KEY before reading it; this block declared it required until then. On a non-2xx, `error` is present and `data` is absent. - `data` TeamDetail, required: The team exactly as `GET /v1/teams` lists it, plus the `stats` aggregate that `GET /v1/teams/{id}/stats` returns. One implementation serves both, so the two cannot disagree. - `id` string, 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. - `sport` 'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football', required - `name` string, required - `short_name` string, nullable - `league` string, nullable: League display name - `logo_url` string, nullable: Treat as opaque; do not construct it. - `flag_url` string, nullable: National-team flag where applicable - `country` string: ISO 3166-1 alpha-3. NOT EMITTED by /v1/teams or /v1/teams/{id} as measured on 2026-09-18; branch on its absence. - `founded_year` integer: NOT EMITTED as measured on 2026-09-18. - `stats` TeamAggregateStats: Aggregate over EVERY finished match we hold for the team, not the current season; `meta.stats_scope` restates that on each response. The goal-shaped names are used for all sports: `goals_scored` is runs in baseball and points in basketball. - `matches_played` integer - `matches_with_scores` integer - `wins` integer - `draws` integer - `losses` integer - `goals_scored` integer - `goals_conceded` integer - `goal_difference` integer - `clean_sheets` integer - `points` integer - `form_string` string, nullable: Most recent results - `btts_rate` number, nullable - `over_2_5_rate` number, nullable - `avg_goals_scored` number, nullable - `avg_goals_conceded` number, nullable - `meta` ResponseMeta: Response metadata. NOTHING here is guaranteed: measured over 38 live envelopes on 2026-09-18, `cached` and `request_id` appeared in 29, `source` in 28, `cache_age_ms` in 9 and `confidence` in 6. This block previously declared all five REQUIRED, which no response has ever satisfied. Treat every field as optional and branch on its absence. Routes add their own keys here (`count`, `limit`, `offset`, `note`, `total`, and per-endpoint ones), so do not assume a closed set. - `date_window` object: Present when ?date= was applied. The exact window the filter used, so an omission at a day boundary is visible. start_utc is inclusive, end_utc exclusive. timezone is UTC, or the zone named by ?tz=, in which case the window is that local day. Boxing card dates are published event dates, so timezone and bounds are null there. - `date` string - `timezone` string, nullable - `start_utc` string, date-time, nullable - `end_utc` string, date-time, nullable - `note` string - `source` 'official-league' | 'aggregator-paid' | 'aggregator-free' | 'community-scraper' | 'forecast' | 'mixed' | 'cache' | 'none' | 'unknown-source' | 'stored' | 'catalogue' | 'gateway' | 'coverage-snapshot': Opaque source-tier label. Customers never see the vendor identity. `forecast` marks a weather forecast (GET /v1/matches/{id}/weather). - `confidence` number, float - `cached` boolean - `cache_age_ms` integer - `request_id` string - `fields_missing` string[] - `note` string: Short factual disclosure about something this response deliberately withheld, present only when there is something to disclose. On live scores it appears when `match_id` could not be resolved to a stored match and was therefore omitted: it gives the counts and points at `/v1/stored/matches`, whose ids you can call back into. Absent when every served id resolves. Distinct from `message`, which explains `coverage: false` or a stale response. This one is attached to a response that DID serve data and names the part of it that is deliberately missing. - `error` ApiError - `code` string, required - `message` string, required - `details` unknown ## Other responses - `404`: no team with that id --- [API](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api.md) · [All operations](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/revisions/31fb54ac414e?raw)