Live scores for one sport or league
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.
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
Query parameters
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).
League code such as epl, laliga, bundesliga, serie_a, ligue1, cl, mls.
ISO date (YYYY-MM-DD) or the literal 'today' (the current UTC date). Selects a UTC calendar day: kickoffs at or after 00:00Z on that date and before 00:00Z the next day. An evening game in the Americas often kicks off after 00:00Z and is listed under the NEXT date. Responses served from stored matches echo the exact window applied in meta.date_window.
Optional IANA time zone name (e.g. America/New_York). ?date= then selects the local calendar day in that zone. The live feed buckets by UTC day, so with ?tz= the response is served from stored matches and meta.date_window shows the window. Offsets such as -05:00 are rejected with 400. Example: ?league=nfl&date=2026-09-13&tz=America/New_York.
Explicit season, labelled by the year it STARTS. Omit for the live window; an explicit past season is subject to the plan's history depth. WHICH SEASON COUNTS AS "CURRENT" IS MEASURED, NOT A CALENDAR DATE (changed 2026-09-25). The depth a plan allows is counted back from the newest season we actually hold played matches for, not from a fixed rollover month. So while a new season is under way but has no results yet; the NHL's 2026-27 opens 2026-09-29, the NBA's 2026-10-03; the previous season stays inside the window, and the window narrows only once the new season has data to narrow to. This only ever widens what a plan reaches; it never moves the boundary earlier than the calendar rule it replaced. ?season= and ?date= on this endpoint now resolve that boundary through one shared rule. Before 2026-09-25 they disagreed for the NBA and the NHL: ?season= counted from the bare calendar year and ?date= from the per-sport boundary, so ?sport=basketball&season=2025 returned 403 while ?sport=basketball&date=2025-12-01 returned 200 on the same key. Both are served now.
Response
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.
Example response
{
"data": {
"scores": {
"value": [
{
"match_id": "71c604d0-0193-4e75-aba4-cc76822e3508"
}
]
}
},
"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.