Data freshness
How fresh is the data, how fast after the final whistle, and what happens during live games.
How fresh is the data?
Short answer: depends on the resource and whether the game is live. The table below is the
contract we operate against: if you observe drift outside these windows, page support with
your request_id.
| Resource | Live in-game | Post-game | Where freshness is recorded |
|---|---|---|---|
| Scoreboard / status | ≤ 30 seconds | n/a | meta.fetched_at |
| Box score | ≤ 90 seconds during play, locked at final | ≤ 5 min | per-resource header |
| Contest detail | ≤ 2 minutes | ≤ 10 min after final | meta.fetched_at |
| Person / team season stats | next morning rebuild | nightly | meta.fetched_at |
| Standings | hourly during the season | hourly | meta.fetched_at |
| Rosters | hourly + on-transaction | hourly | meta.fetched_at |
| Injuries | hourly | hourly | source_observed_at (current status), covered_through (history) |
| Competition schedules | nightly + on-change | nightly | meta.fetched_at |
Live windows
A game is "live" from puck/tip/first-pitch drop until the final-confirmed marker. During this window, we suppress some long TTLs and re-poll upstreams aggressively. Two consequences:
- Cache hit rate drops: expect
meta.cache: "MISS"for box scores in active games. - Read-your-write timing: back-to-back calls might see different
fetched_atvalues inside the same minute. That is correct behaviour, not a bug.
What freshness is not
- Not a real-time push channel. The API is HTTP: poll, don't stream. We may publish a WebSocket feed for live windows; that's not a v1 commitment.
- Not a live odds feed. Pregame contest/person boards and paged history live on
/v1/.../odds(discovery 1× · spot board 5× · history page 10×; see Quotas). We do not serve in-play ticks./v1/analysis/player-propstill accepts alineyou supply. - Not historical replay. Older seasons can have sparse phase coverage.
Check
gamesand the per-windowaverages.counts.*before treating an average as reliable. - Not injury coverage for every league. Injury data is hourly for the five leagues listed in Injuries, and absence only means healthy inside a source's coverage window. Read that page before inferring availability from a missing field.
Polling cadence
A polite client polls box scores at 30–60 second intervals during live games and never more than once per minute for non-live resources. The per-minute rate limit defaults to 100; you can hold a comfortable polling loop well inside that ceiling.
See Rate limits for the headers that tell you exactly how much window you have left.