Getting started
Data freshness
Responses are served from our store and refreshed from the source as they age. The live state of a match — status, score, clock, winner — comes from the source’s live feed and is current to the second in every response that carries the fixture. How old the rest can be while the data is changing, at worst, with the source healthy (during a source outage we keep serving the last copy we have rather than an error):
| Endpoint | How current |
|---|---|
| WebSocket, /v2/livescores, /v2/sports | Real time: pushed from the source’s live feed within seconds. Esports period scores (League of Legends kills per game), which the feed sends only every few minutes, within about 15 seconds while the fixture has a fixture:{id} subscriber. |
| Status, score, clock and winner of a fixture in play or just finished — wherever a Fixture appears | Seconds. Every response that embeds fixtures (fixture detail, livescores by sport, fixtures by date, team / player / round fixtures) is brought up to the live feed when it is served. |
| /v2/livescores?sport= | A match that ended leaves at once; a match that just started joins within about a minute. |
| /v2/fixtures/{id} (other fields) | About a minute while in play; final once finished. Before kick-off: a new start time or a postponement is picked up on the first request after the source announces it. |
| /v2/fixtures/{id}/lineups, statistics, events, play-by-play, best-players, momentum, shotmap, points, scorecard, average-positions, heatmap, form, streaks | About 30 seconds while in play (at most 90); settled once finished. On a fixture:{id} WebSocket channel (Business) events, statistics and lineups are pushed when they change: events about 20–45 seconds after a goal, red card or period change (when the source’s REST lists it), otherwise within about 30 seconds; statistics and lineups within about 30–60 seconds. |
| fixture:{id} WebSocket play by play, momentum, shot map (Business) | Play by play about 20 seconds after the source lists an entry (football, basketball); momentum and shot map about 30 seconds (football); a last push after full time. |
| /v2/fixtures/{id}/umpires, weather, games | About 30 seconds (at most 90) while the match is in play; before it, up to 13 minutes; once finished, up to 30 hours. |
| /v2/fixtures/{id}/h2h, /h2h/fixtures | Refreshed after the fixture ends; otherwise up to 30 hours. Status and score of the listed fixtures are brought up to the live feed when served. |
| /v2/fixtures/{id}/win-probability | Recomputed at most every 15 seconds while in play, from the events, shot map and momentum above (about 30 seconds old); final and kept once finished. The pre-match estimate is fixed at kick-off. |
| /v2/fixtures/{id}/commentary | An entry usually appears within a minute of the event (the events above are about 30 seconds old, then a few seconds to write it); written while someone follows the match — and always for the featured top-league matches shown on sportsapi.app/live — and never rewritten. |
| /v2/fixtures?date= (which fixtures a day holds) | A fixture moved to another day, postponed or ended is refreshed on the next request, on both days. Otherwise a few minutes for today and ahead (at most 13); hours for past days, never once every fixture is finished. |
| /v2/teams/{id}/fixtures | A match joins recent on the first request after kick-off; both lists refresh on the first request after one of the team’s matches ends, is moved or is postponed; otherwise up to 13 minutes (upcoming) or 2.5 hours (recent). |
| /v2/leagues/{id}/fixtures | Which fixtures a round lists: refreshed after one of them ends, is moved or is postponed; otherwise up to 13 minutes. |
| Start time and postponement of a fixture not yet started — wherever a Fixture appears | A new start time or a postponement we have seen (on the live feed or in any response from the source) is applied to every list holding the fixture when it is served. |
| /v2/players/{id}/fixtures, /seasons, /statistics | Refreshed after a match the player was in the lineup — or the squad — of ends (the request after the next one sees it; the source updates season statistics with a delay); the fixtures list also when such a match is moved or postponed. A new match in the fixtures list otherwise up to 13 minutes; seasons and statistics up to 6 hours. |
| /v2/referees/{id}, /v2/managers/{id}, /v2/teams/{id}/trophies, /v2/teams/{id}/career-statistics | Up to 6 hours, rarely up to 30. |
| /v2/referees/{id}/fixtures, /v2/managers/{id}/fixtures | Up to 13 minutes; the status, score and clock of a match in play are current to the second. |
| /v2/teams/{id}/position-history, the form column of /v2/leagues/{id}/standings | Refreshed on the first request after a match of the season ends; otherwise up to 2.5 hours. |
| /v2/leagues/{id}/standings | Refreshed on the first request after a match of the season ends, and again 2 minutes later (the source can lag the final whistle); otherwise up to 13 minutes. |
| /v2/leagues/{id}/cup-trees | Refreshed on the first request after a match of the season ends; otherwise up to 13 minutes. |
| /v2/leagues/{id}/top-players, top-teams, /v2/teams/{id}/statistics | Refreshed after a match of the season ends (the request after the next one sees it); the source itself updates these with a delay. |
| /v2/teams/{id}/squad, /v2/players/{id} (the current team) | Refreshed on the next request once a move shows anywhere we look: a lineup naming a player the squad lacks, a squad or profile we refetch, or a transfers list. The transfers lists of teams read in the last 7 days are checked once a day, so their squads and profiles follow a move within about a day. Otherwise up to 6 hours, rarely up to 30 — the source does not announce transfers. |
| /v2/rankings/{type}, /v2/categories, /v2/leagues (directory), /v2/series (directory), /v2/teams/{id}/leagues, /v2/leagues/{id}/player-statistics | Up to 6 hours, rarely up to 30. The player-statistics explorer is not refreshed after a match — the source updates season statistics with a delay anyway. |
| /v2/races, /v2/races/{id} | On a race:{id} WebSocket channel (Business, since 2026-10-24) changes are pushed: the race within about 60 seconds, a running session’s results within about 30. Over REST: while a session runs or starts within 15 minutes: about 30 seconds (at most 90); before: up to 13 minutes; once every session is over: up to 30 hours. |
| /v2/races/{id}/results | Follows the session it classifies (without session=, the race): while it runs or starts within 15 minutes, about 30 seconds (at most 90); finished: up to 13 minutes while rows still change, up to 30 hours once nothing changed for 6 hours; not started yet: up to 13 minutes. |
| /v2/series/{id}/standings, /v2/series/{id}/races | Up to 13 minutes while rows still change; up to 30 hours once nothing changed for 6 hours (a season’s race list: once every race is over). |
| Transfers, seasons, rounds, search | Up to 6 hours, rarely up to 30 (a key nobody asked for in a day is served once more while it refreshes); search up to 13 minutes. The source’s transfer lists are current to the day. |