Rate Limits
How rate limiting and caching work, and how to make the most of your requests.
Rate Limit
30 / min
Per IP address, sliding window
Server Cache
5 min
s-maxage=300 on all responses
Stale Revalidate
10 min
stale-while-revalidate=600
Rate Limiting
All endpoints share a single rate limit of 30 requests per minute per IP address, enforced using a sliding window.
When you exceed the limit, the API returns a 429 Too Many Requests status. Wait until the window resets before retrying.
The rate limit is designed to be generous for typical use cases. If you need higher limits for a specific project, reach out and we can discuss.
Caching
Every response includes a Cache-Control header:
Cache-Control: public, s-maxage=300, stale-while-revalidate=600This means CDNs and proxies will cache responses for 5 minutes, and serve stale data for up to 10 minutes while revalidating in the background. Your application can benefit from this by respecting cache headers.
Best Practices
Cache responses locally
Stats update at most once per day. Fetching more than once every 5 minutes returns identical data.
Batch by sport, not by team
Each endpoint returns all teams for a sport in one call. There is no per-team endpoint.
Use the seasons endpoint
Call /v1/stats/seasons/:sport once to get available seasons, then pass the season parameter explicitly.
Handle 429s gracefully
If you get rate limited, wait 60 seconds and retry. Avoid tight retry loops.