TheRundown API enforces rate limits to ensure fair usage and platform stability. Limits are applied per API key, meaning all requests made with the same key count toward a shared quota regardless of the originating IP address or service.
Rate Limit Tiers
Different subscription tiers have different rate limit allowances. The table below outlines the general structure.
| Tier | Requests per Minute | Requests per Day | Notes |
|---|
| Free | 20 | 1,000 | Suitable for personal projects and evaluation. |
| Standard | 60 | 50,000 | Recommended for most production applications. |
| Pro | 300 | 500,000 | Designed for high-frequency polling use cases. |
| Enterprise | Custom | Custom | Tailored limits based on your requirements. |
The exact limits for your key depend on your subscription. The values above are representative. Contact support if you need to confirm or adjust your tier.
| Header | Description |
|---|
X-RateLimit-Limit | The maximum number of requests allowed in the current window. |
X-RateLimit-Remaining | The number of requests remaining in the current window. |
X-RateLimit-Reset | The UTC epoch timestamp (in seconds) when the current window resets. |
curl -I -H "X-TheRundown-Key: YOUR_API_KEY" \
"https://api.therundown.io/v2/sports/2/events"
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1700000000
What Happens When You Hit the Limit
When your rate limit is exceeded, the API returns a 429 Too Many Requests response. The response body contains an error message and the X-RateLimit-Reset header indicates when you can resume making requests.
{
"error": "rate limit exceeded",
"message": "You have exceeded your rate limit. Please wait before making additional requests."
}
Best Practices
Use Delta Endpoints for Efficient Polling
Rather than fetching the full event list on every poll cycle, use the delta endpoints to retrieve only events that have changed since your last request. This dramatically reduces the number of API calls required and keeps you well within your rate limit.
# Full event list (expensive, use sparingly)
curl -H "X-TheRundown-Key: YOUR_API_KEY" \
"https://api.therundown.io/v2/sports/2/events"
# Delta endpoint (efficient, returns only changes)
curl -H "X-TheRundown-Key: YOUR_API_KEY" \
"https://api.therundown.io/v2/sports/2/events/delta"
Use WebSocket for Real-Time Data
If your application needs real-time updates (live scores, line movements), use TheRundown WebSocket feed instead of repeatedly polling REST endpoints. WebSocket connections deliver data as it changes and do not count against your REST API rate limit.
Implement Exponential Backoff
When you receive a 429 response, do not retry immediately. Use exponential backoff with jitter to spread out retry attempts.
import time
import random
import requests
def fetch_with_backoff(url, headers, max_retries=5):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code != 429:
return response
wait = (2 ** attempt) + random.uniform(0, 1)
print(f"Rate limited. Retrying in {wait:.1f}s...")
time.sleep(wait)
raise Exception("Max retries exceeded")
Cache Responses Where Possible
Reference data such as the sports list (/v2/sports) and affiliates list (/v2/affiliates) changes infrequently. Cache these responses locally and refresh them on a longer interval (e.g., once per day) rather than fetching them on every application startup.
Requesting Higher Limits
If your use case requires higher rate limits than your current tier provides, contact TheRundown support at [email protected] or reach out through your account dashboard. Include the following information to expedite the request:
- Your API key (or the email associated with your account)
- Your current tier
- The rate limit you need and why
- A brief description of your application or use case
