---
title: "Matches for a team"
method: GET
path: "/v1/teams/{id}/matches"
tags: ["teams"]
---

# Matches for a team

`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

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

## Path parameters

- `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.

## Query parameters

- `sport` 'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football', required
- `season` string
- `limit` integer
- `offset` integer
- `page` integer

## Response `200`

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

- 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` union, required
    - object
      - `historical` FieldResult
        - `value` unknown, required
        - `source` string, required
        - `via` 'api' | 'cache' | 'mcp', required
        - `confidence` number, required
        - `fetchedAt` string, date-time, required
        - `ttlSeconds` integer, required
    - Match[]
      - `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
      - `league` string, required: The league's DISPLAY name as served here (e.g. "MLB", "NHL"). This is not the `?league=` code; see LeagueCode for that.
      - `kickoff_utc` string, date-time, required
      - `status` 'scheduled' | 'live' | 'in_progress' | 'finished' | 'postponed' | 'cancelled' | 'suspended', required
      - `home` MatchSide, required: One side of a match. The field names are `id`/`name`; there is no `team_id`/`team_name` here. Until 2026-09-18 this schema said `team_id` + `team_name`, which no endpoint has ever returned.
        - `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.
        - `name` string, required
        - `short_name` string, nullable
        - `logo_url` string, nullable: Served from our own asset endpoint; treat it as opaque and do not construct it.
      - `away` MatchSide, required: One side of a match. The field names are `id`/`name`; there is no `team_id`/`team_name` here. Until 2026-09-18 this schema said `team_id` + `team_name`, which no endpoint has ever returned.
        - `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.
        - `name` string, required
        - `short_name` string, nullable
        - `logo_url` string, nullable: Served from our own asset endpoint; treat it as opaque and do not construct it.
      - `score` MatchScore: Final or current goal/run/point totals. Null on a match with no score yet.
        - `home` integer, nullable, required
        - `away` integer, nullable, required
      - `linescore` Linescore: Per-period totals. The array length and meaning follow the sport, and are not uniform even within one sport, so read it positionally only after checking `sport`.
        - `home` integer[]
        - `away` integer[]
      - `attendance` integer, nullable
      - `broadcast` string, nullable
      - `has_odds` boolean: Whether stored odds exist for this match; see /v1/matches/{id}/odds.
      - `round` string, nullable: Competition segment as the source names it, e.g. "Regular Season - 2" or "Group Stage". This is the axis to group gameweek analytics by: a postponed fixture keeps its round while its kickoff_utc moves by weeks, so bucketing by date splits one gameweek and merges another. Free text rather than an integer, because the phase carries meaning an integer would discard. Null where the source supplies none, currently populated for soccer only.
      - `season` string: NOT EMITTED by the list endpoints as measured on 2026-09-18. Declared because callers may hold it from older payloads; branch on its absence rather than expecting it.
      - `venue` string: NOT EMITTED by the list endpoints as measured on 2026-09-18.
      - `updated_at` string, date-time: NOT EMITTED by the list endpoints as measured on 2026-09-18.
  - `meta` object: 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

- `400`: Missing or invalid ?sport=, or an invalid ?season=/?limit=.

---

[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)