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 |
| 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 market data. Lines, prices, and odds are out of scope.
/v1/analysis/player-propaccepts alineparameter and returns hit rates against it, but the line itself is yours to supply. - Not historical replay. Older seasons can have sparse phase coverage.
Check
gamesandhit_rate.gamesbefore treating the average as reliable.
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.