Rate Limits

TheRundown API enforces usage controls per API key. There are two separate systems to understand:

Data-point billing tracks how much data you consume across REST and WebSocket traffic.
Per-second throttling protects the platform from bursty request patterns.

If you are building production workloads, you should monitor both. A key can stay under its requests-per-second ceiling and still run out of included data points, or vice versa.

How Usage Is Enforced

1. Data points

Most API endpoints return an X-Datapoints header. That number represents how many billable data points the response consumed. In practice:

large snapshots across many sportsbooks and markets cost more than narrow, filtered responses
delta endpoints are usually much cheaper than repeatedly fetching full event payloads
WebSocket messages are also metered as data points, even though they do not increment the HTTP request counter

Free keys have a daily included cap. Paid plans have monthly included data points and, on self-serve tiers, overage pricing after the included amount. Plans billed weekly meter a proportional weekly share of the tier’s allowance instead — see Weekly Billing below.

2. Burst throttling

Every key also has a per-second request ceiling. This is separate from billing and exists to prevent request storms. If you exceed that burst limit, the API returns 429 Too Many Requests with a short Retry-After value, usually 1.

3. WebSocket behavior

WebSocket traffic does not increment your HTTP request counter, but it is still part of your metered usage. Treat subscriptions the same way you treat REST queries: filter aggressively and only subscribe to the sports, markets, and books you actually need.

Current API Tier Defaults

Tier	Included data points	Overage	Burst limit	Data delay	WebSocket
Free	`20,000/day`	No overage	`1 req/sec`	`5 min`	No
Starter	`5,000,000/mo`	`$0.002/pt`	`2 req/sec`	`60 sec`	No
Pro	`25,000,000/mo`	`$0.001/pt`	`5 req/sec`	`30 sec`	No
Ultra	`100,000,000/mo`	`$0.0005/pt`	`10 req/sec`	Real-time	Yes
Super	`250,000,000/mo`	`$0.0004/pt`	`15 req/sec`	Real-time	Yes
Mega	`500,000,000/mo`	`$0.0003/pt`	`20 req/sec`	Real-time	Yes
Max	`2,500,000,000/mo`	`$0.0001/pt`	`50 req/sec`	Real-time	Yes
Enterprise	Custom	Custom	Custom	Real-time	Yes

Sportsbook coverage, periods, history access, and other entitlements also vary by tier. Two to be aware of: player prop markets require Starter or higher (Free keys do not receive them), and live game state / play-by-play data requires Ultra or higher. The live response headers are the best way to confirm what a specific API key can access right now.

Weekly Billing

Every paid API tier is also available on a weekly billing cadence for workloads that don’t need a month-long commitment — for example, covering a single tournament or a few weeks of a season. Weekly plans are priced at a premium over the equivalent monthly plan (the commitment ladder is weekly > monthly > annual). On a weekly plan, your included data points are a proportional weekly share of the tier’s monthly allowance (monthly × 12 ÷ 52 — e.g. Starter weekly includes 1,153,846 data points per week), metered over your 7-day billing window. Overage beyond the weekly allowance is billed at the same per-data-point rates as the monthly tier. The usage headers tell you which window applies to your key: X-Datapoints-Period reports weekly on weekly-billed plans (with X-Datapoints-Reset marking the end of the current 7-day window), monthly on monthly and annual plans, and daily on the Free tier.

Usage Headers

Metered responses include usage and entitlement headers you can surface in logs, dashboards, and upgrade prompts.

Header	Description
`X-Datapoints`	Data points consumed by this response
`X-Datapoints-Used`	Total data points used in the current billing window
`X-Datapoints-Remaining`	Included data points remaining before the next reset
`X-Datapoints-Limit`	Included data points for the current window
`X-Datapoints-Period`	Cadence of the quota window: `daily` (Free tier), `weekly` (weekly-billed plans), or `monthly`
`X-Datapoints-Reset`	ISO 8601 timestamp for the current usage window reset
`X-Datapoints-Credit-Balance`	Bonus data-point credits applied on top of the allowance, when present
`X-Datapoints-Credit-Expiry`	Expiry timestamp for the credit balance, when present
`X-Tier`	Current subscription tier
`X-Rate-Limit`	Allowed requests per second for this key
`X-Data-Delay-Seconds`	Delay applied to returned data for this key
`X-Bookmakers`	Sportsbook IDs this key can access, or `all`
`X-Periods`	Period IDs this key can access, or `all`
`X-History-Access`	Whether this key can access historical line data
`X-Live-Odds-Access`	Whether this key can access live odds
`X-Websocket-Access`	Whether this key can connect to WebSocket feeds

curl -i -H "X-TheRundown-Key: YOUR_API_KEY" \
  "https://therundown.io/api/v2/sports/4/events/2026-02-26?market_ids=1,2,3&affiliate_ids=19,23&main_line=true&offset=300"

Example headers:

X-Datapoints: 452
X-Datapoints-Used: 120348
X-Datapoints-Remaining: 4879652
X-Datapoints-Limit: 5000000
X-Datapoints-Period: monthly
X-Datapoints-Reset: 2026-03-31T00:00:00Z
X-Tier: starter
X-Rate-Limit: 2
X-Data-Delay-Seconds: 60
X-Bookmakers: 19,22,23
X-Periods: all
X-History-Access: false
X-Live-Odds-Access: false
X-Websocket-Access: false

On 429 responses caused by billing caps, the billing headers remain useful. Read Retry-After and the X-Datapoints-* headers before deciding whether to retry or upgrade.

Understanding `429 Too Many Requests`

Not every 429 means the same thing. There are three common cases.

1. Burst rate limit exceeded

You sent too many requests in a short interval for your tier.

{
  "error": "Rate limit exceeded",
  "limit": 2,
  "upgrade_url": "/pricing/api",
  "upgrade_message": "You've exceeded your plan's rate limit. Upgrade for a higher requests-per-second limit."
}

Look at Retry-After before retrying.
Queue or batch work instead of firing many concurrent requests.
Switch recurring update loops to delta polling or WebSocket where appropriate.

2. Daily data-point cap reached

This is the free-tier hard cap.

{
  "error": "Daily data point limit reached",
  "limit": 20000,
  "used": 20000,
  "upgrade_url": "/pricing/api",
  "upgrade_message": "You've hit the free tier's daily limit. Upgrade to a paid plan for a higher monthly allowance and rate limits."
}

Retry-After tells you how long until the next daily window begins.
X-Datapoints-Remaining will be 0.
The fix is to wait for reset or move to a paid plan.

3. Monthly data-point cap reached

This appears on plans or accounts that are configured with a hard monthly cap.

{
  "error": "Monthly data point limit reached",
  "limit": 25000000,
  "used": 25000000,
  "period": "monthly",
  "upgrade_url": "/pricing/api",
  "upgrade_message": "You've reached your plan's monthly data-point limit. Upgrade for a higher allowance, or enable overage billing to keep going."
}

Treat this as a billing-window issue, not a short retry.
Read Retry-After and X-Datapoints-Reset.
If this is unexpected on a paid account, contact support with the response headers.

Best Practices

Filter aggressively

The biggest usage lever is almost always response shape. Start every integration by narrowing:

market_ids
affiliate_ids
event_ids
main_line=true
hide_closed_markets=1 where available

Use delta endpoints for ongoing updates

Instead of fetching the full event list repeatedly, bootstrap once and poll:

GET /api/v2/delta for changed event objects
GET /api/v2/markets/delta for individual price changes

See the Efficient Polling guide for the full pattern.

Use WebSocket on real-time tiers

For live screens and line-movement monitoring, WebSocket is usually the best delivery model once your plan includes it. It avoids HTTP burst limits, but you should still keep subscriptions tight because pushed messages are metered.

Cache reference data

Sports, affiliates, teams, and market definitions change far less often than live odds. Cache them locally and refresh on a longer interval.

Alert before users run out

If you are building on behalf of end users or internal analysts, instrument alerts when usage reaches 70%, 85%, and 100% of included data points. The headers above make this straightforward.

Need More Throughput?

If your workload needs more data points, higher burst limits, or real-time access, contact support at [email protected] or use your dashboard. Include:

Your API key (or the email associated with your account)
Your current tier
Approximate data-point volume per day or month
Required requests-per-second ceiling
Whether you need WebSocket, historical data, or broader sportsbook coverage
A short description of your application or workload

Getting Started

Reference Tables

How Usage Is Enforced

1. Data points

2. Burst throttling

3. WebSocket behavior

Current API Tier Defaults

Weekly Billing

Usage Headers

Understanding `429 Too Many Requests`

1. Burst rate limit exceeded

2. Daily data-point cap reached

3. Monthly data-point cap reached

Best Practices

Filter aggressively

Use delta endpoints for ongoing updates

Use WebSocket on real-time tiers

Cache reference data

Alert before users run out

Need More Throughput?

​How Usage Is Enforced

​1. Data points

​2. Burst throttling

​3. WebSocket behavior

​Current API Tier Defaults

​Weekly Billing

​Usage Headers

​Understanding 429 Too Many Requests

​1. Burst rate limit exceeded

​2. Daily data-point cap reached

​3. Monthly data-point cap reached

​Best Practices

​Filter aggressively

​Use delta endpoints for ongoing updates

​Use WebSocket on real-time tiers

​Cache reference data

​Alert before users run out

​Need More Throughput?

How Usage Is Enforced

1. Data points

2. Burst throttling

3. WebSocket behavior

Current API Tier Defaults

Weekly Billing

Usage Headers

Understanding `429 Too Many Requests`

1. Burst rate limit exceeded

2. Daily data-point cap reached

3. Monthly data-point cap reached

Best Practices

Filter aggressively

Use delta endpoints for ongoing updates

Use WebSocket on real-time tiers

Cache reference data

Alert before users run out

Need More Throughput?