Getting started · Data freshness
How old can a response be?
Wherever a response includes a match's live state — status, score, clock and winner — that state is accurate to the second. All other data is re-read from the source as it gets older, at a pace set by the kind of data and by whether a match is under way. The sections below give the worst case for each endpoint family.
Five speeds
Real time
Live match state comes straight from the source's live feed and is applied at the moment a response is served.
Real time· pushed, or current to the second
Delivered within seconds of the live feed. The one gap is esports period scores — kills per game in League of Legends, say — which the feed refreshes only every few minutes; while a fixture:{id} channel has a subscriber, we fill those in within about 15 seconds.
- Status, score, clock and winner — wherever a Fixture appears
Seconds, for a fixture in play or just finished. Any response that embeds fixtures — the fixture itself, livescores by sport, fixtures by date, a team's, player's or round's fixtures — is brought level with the live feed as it is served.
- Kick-off time and postponement — wherever a Fixture appears
Covers fixtures that have not kicked off yet. Once we learn of a rescheduled kick-off or a postponement — from the live feed or from any other source response — every list containing that fixture shows the change the next time it is served.
Seconds to a minute
Fast-moving detail that is derived from the live feed or pushed over the WebSocket as soon as it changes.
Seconds· ≈ 1 s to 1 min
A match that ends drops off immediately; one that has just kicked off appears within about a minute.
Everything besides the live state is at most about a minute old during play and final after the match. Ahead of kick-off, once the source announces a rescheduled start or a postponement, the next request picks it up.
During play the model reruns no more often than every 15 seconds, fed by the events, shot map and momentum endpoints — inputs that lag about 30 seconds themselves. When the match ends the curve is final and stored for good; the pre-match estimate stops changing at kick-off.
Entries normally appear less than a minute after the moment they describe — the underlying events lag about 30 seconds, and writing adds a few more. We write commentary for any match someone is following, and for featured top-league matches in every case. A published entry is never edited.
Each change is pushed when it happens. Events: roughly 20–45 seconds after a goal, a red card or a change of period (counted from when the source's own REST shows it), and within roughly 30 seconds for anything else. Statistics and lineups: roughly 30–60 seconds. Play by play (football and basketball): roughly 20 seconds behind the source's entry. Momentum and shot map (football): roughly 30 seconds. A final push is sent after full time.
Changes to the race itself are pushed within about 60 seconds, and the classification of a running session within about 30.
About 30 seconds
Per-match detail that is re-read from the source on a short cycle while the game or session is running, then settles.
~30 s· at most 90 s, while in play
- /lineups/statistics/events/play-by-play/best-players/momentum/shotmap/points/scorecard/average-positions/heatmap/form/streaks
All under /v2/fixtures/{id}. About 30 seconds while the match is in play, never more than 90; settled once it is finished.
Same rhythm as the match heatmap: about 30 seconds in play (at most 90), settled after the final whistle.
Under /v2/fixtures/{id}. About 30 seconds (at most 90) during the match; up to 13 minutes before it; up to 30 hours once it is finished.
Roughly 30 seconds behind during play (90 at worst), then fixed once the game ends.
Pre-match, REST serves prices up to 13 minutes old, or about 2 minutes old while anyone is following odds:{id}. During play, REST lags about 30 seconds (90 at most) and the odds:{id} channel (Business) pushes each price change within about a second. Settlement arrives a few minutes after the final whistle for every market the source settles; it does not settle all of them, and the endpoint page names the exceptions.
About 30 seconds in play (at most 90); up to 13 minutes before kick-off; up to a day after the match.
About 30 seconds (90 at most) whenever a session is live or due to begin in the next 15 minutes; up to 13 minutes earlier than that; up to 30 hours after the last session has ended. For quicker updates, subscribe to the race:{id} channel (see above).
Follows whichever session it classifies — the race as a whole when session= is omitted. A session that is live or begins within the next 15 minutes: about 30 seconds behind, 90 at most. A session that has not begun: up to 13 minutes. A finished session: up to 13 minutes as long as its rows keep changing, then up to 30 hours after 6 hours without a change.
Follows its session the same way: about 30 seconds while it runs (at most 90), then settled for up to 30 hours after it is finished.
Up to 13 minutes
Schedules, tables and lists. Most of them refresh on the first request after a relevant match ends, moves or is postponed, and otherwise within 13 minutes.
≤ 13 min· or the next request after a match changes
The list of fixtures on a given day. When a fixture is rescheduled to a different day, postponed or completed, the next request refreshes both affected days. Beyond that, today and future days lag a few minutes (13 at most) and past days a few hours — and a day whose fixtures have all finished is never refreshed again.
liveCount comes from the live index in real time. The counts per day lag a few minutes from today onward (13 at most) and hours for earlier days.
Once a match kicks off, the next request shows it under recent. When any of the team's matches finishes, is rescheduled or is postponed, the first request afterwards rebuilds both lists. Without such a trigger, upcoming is at most 13 minutes old and recent at most 2.5 hours.
A round's fixture list is rebuilt when one of its matches finishes, is rescheduled or is postponed, and is never more than 13 minutes old otherwise.
A finished match that had the player in its lineup or squad triggers a refresh: it starts on the next request and is visible on the one after (the source adds season statistics with a lag of its own). The fixtures list is also rebuilt if one of those matches is rescheduled or postponed. Without a trigger, new matches reach the fixtures list within 13 minutes, and seasons and statistics within 6 hours.
The first request after any match of the season finishes rebuilds the table, and a second rebuild follows 2 minutes later because the source can lag behind the final whistle. With no finished match, 13 minutes at most.
Rebuilt by the first request that follows the end of any match in the season; never older than 13 minutes otherwise.
The choice of featured match can be up to 13 minutes old; once that match is in play, its status, score and clock are accurate to the second.
13 minutes at the outside; matches in play carry their live state to the second.
When the source schedules another game in the series, it appears within 13 minutes.
Clips tend to land hours after full time, so a recent match is re-checked at least every 13 minutes; once the match is several days old, up to 30 hours.
Today and future days: 13 minutes at most. Past days: 30 hours at most.
13 minutes at most while the rows keep moving. After 6 hours with no change — or, for the race list of a season, after its final race — up to 30 hours.
13 minutes at most.
Hours
Profiles, directories and season-long figures. The source itself updates many of these some time after a match, so polling faster gains nothing.
6–30 h· up to 6 h, rarely up to 30 h
Normally 6 hours at most, occasionally as much as 30.
- /v2/leagues/popular/v2/leagues/{id}/team-of-the-week…/team-of-the-week/periods/v2/players/{id}/attributes/v2/venues/{id}
Normally 6 hours at most, occasionally as much as 30. A team of the week stays fixed once published, and the next round or week shows up inside the same window.
- /v2/players/{id}/national-team/career/heatmap/ratings/v2/teams/{id}/rankings/v2/teams/{id}/top-players/v2/leagues/{id}/player-of-the-season…/player-of-the-season/race
Normally within 6 hours, occasionally 30. Polling harder will not help: the source only revises season figures a while after each match.
- /v2/players/{id}/statistics/rankings/v2/teams/{id}/goal-distribution/v2/teams/{id}/year-statistics/v2/leagues/{id}/champions/v2/leagues/{id}/teams
Normally within 6 hours, occasionally 30; as above, the source revises these numbers with a delay after each match.
- /v2/rankings/{type}/v2/categories/v2/leagues/v2/series/v2/teams/{id}/leagues/v2/leagues/{id}/player-statistics
Normally within 6 hours, occasionally 30. A finished match does not trigger a refresh of the player-statistics explorer — the source's season statistics arrive late in any case.
The source never announces transfers, so we watch for them. As soon as one of our reads reveals a move — a lineup with a player missing from the squad, a fresh copy of a squad or profile, or a transfer list — the next request is refreshed. For teams requested within the last 7 days we check the transfer lists once a day, which keeps their squads and profiles no more than about a day behind a move. In all other cases, normally within 6 hours, occasionally 30.
Normally within 6 hours, occasionally 30. If no one has asked for an item in a day, the first request gets the stored copy one last time while a fresh one is fetched. The source's own transfer lists are up to date to within a day.
The fixture finishing triggers a refresh; without that, up to 30 hours. Each listed fixture still takes its status and score from the live feed at serve time.
- /v2/teams/{id}/position-historyform column of standings
Rebuilt on the first request after any match of the season finishes; never older than 2.5 hours otherwise.
A finished match of the season starts a refresh on the next request, visible on the one after; the source itself posts these figures late.
Polling at the pace of the data
Every request counts against your quota, including the ones that return what you already had. Match your polling to the tier.
Subscribe instead of polling: the WebSocket and webhooks push each change (Business). On other plans, poll
/v2/livescoreswithin your per-minute rate.While a match is in play, asking more often than every 30 seconds mostly returns the bytes you already have.
Re-read after a match you care about ends — that request is what triggers the refresh — and otherwise every few minutes at most.
Cache for hours. A daily refresh is plenty for profiles, directories and career tables.
Quota arithmetic and the per-minute rate are covered in Plans, quota & rate limits.