> ## 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.

### 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    | `2,000,000/mo`       | `$0.002/pt`  | `2 req/sec`  | `60 sec`   | No        |
| Pro        | `10,000,000/mo`      | `$0.001/pt`  | `5 req/sec`  | `30 sec`   | No        |
| Ultra      | `40,000,000/mo`      | `$0.0005/pt` | `10 req/sec` | Real-time  | Yes       |
| Super      | `100,000,000/mo`     | `$0.0004/pt` | `15 req/sec` | Real-time  | Yes       |
| Mega       | `200,000,000/mo`     | `$0.0003/pt` | `20 req/sec` | Real-time  | Yes       |
| Max        | `1,000,000,000/mo`   | `$0.0001/pt` | `50 req/sec` | Real-time  | Yes       |
| Enterprise | Custom               | Custom       | Custom       | Real-time  | Yes       |

<Note>
  Sportsbook coverage, periods, history access, and other entitlements also vary by tier. The live response headers are the best way to confirm what a specific API key can access right now.
</Note>

## 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`    | `daily` or `monthly`                                  |
| `X-Datapoints-Reset`     | ISO 8601 timestamp for the current usage window reset |
| `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: 1879652
X-Datapoints-Limit: 2000000
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
```

<Info>
  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.
</Info>

## 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
}
```

* 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
}
```

* `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": 10000000,
  "used": 10000000,
  "period": "monthly"
}
```

* 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