---
title: "Live scores for one sport or league"
method: GET
path: "/v1/scores"
tags: ["matches"]
---

# Live scores for one sport or league

`GET /v1/scores`

## Request

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

The live per-adapter scores feed. Unlike /v1/matches (which returns an ARRAY of match objects with team identities, league and kickoff), this returns the raw live-scores field envelope, in which `home` and `away` are integer SCORES and the match is keyed as `match_id`. Requires ?sport= or ?league=: a live fetch dispatches on an adapter, and with no sport there is nothing to dispatch on. This payload was previously reachable only through /v1/matches for single-league sports (baseball, boxing) as a side effect of a performance guard; callers of that shape should move here, and the URL is the only change required.

## Query parameters

- `sport` 'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football'
- `league` string: 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).
- `date` string
- `tz` string
- `status` 'scheduled' | 'live' | 'in_progress' | 'finished' | 'postponed' | 'cancelled' | 'suspended'
- `season` integer
- `limit` integer
- `offset` integer

## Response `200`

The live-scores field envelope. `data.scores` is null when no adapter covers the sport/league, in which case meta.coverage is false: a 200 that makes no claim about the data, rather than an error about the request.

- 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` object, required
    - `scores` object, nullable: A FieldResult whose `value` is the live score array. Null when no adapter covers the sport/league, in which case meta.coverage is false.
      - `value` Score[], required: The canonical value for this field. Shape varies by FieldKey.
        - `match_id` string, uuid: Stored match id, usable as-is with `/v1/matches/{id}`, `/v1/stored/matches/{id}/stats` and the other id-taking endpoints. OMITTED when this live row cannot be resolved to a match we hold; an absent id is a condition you can branch on, an id that does not resolve is not. The scores on such a row are still real.
        - `home` integer, nullable, required
        - `away` integer, nullable, required
        - `status` 'scheduled' | 'live' | 'in_progress' | 'finished' | 'postponed' | 'cancelled' | 'suspended', required
        - `period_scores` PeriodScore[]
          - `period` integer, required
          - `label` string, required
          - `home` integer, required
          - `away` integer, required
        - `clock` Clock
          - `elapsed_seconds` integer, required
          - `period` integer, required
          - `added_seconds` integer
        - `updated_at` string, date-time, required
      - `source` string, required
      - `via` 'api' | 'cache' | 'mcp', required
      - `confidence` number, required
      - `fetchedAt` string, date-time, required
      - `ttlSeconds` integer, required
  - `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

- `400`: Missing or unknown sport/league. Unlike /v1/matches there is no bare all-sports fallback here, because a live fetch has no adapter to dispatch on without a sport.

---

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