> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therundown.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Rate Limits
> Understand data-point billing, per-second throttles, usage headers, and the different 429 responses you can receive.
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](#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 |
```bash theme={null}
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:
```text theme={null}
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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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](/guides/efficient-polling) 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 **[support@therundown.io](mailto:support@therundown.io)** 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