Efficient Polling - TheRundown API

Polling the full events endpoint every few seconds is expensive, burns data points, and can trip your per-second throttle if you scale it across many sports or books. This guide covers how to keep data fresh without paying for or requesting far more than you need.

Why Polling Efficiency Matters

TheRundown usage is not just about request count. The cost of a polling loop depends on:

how many sportsbooks you request
how many markets you include
whether you pull full event payloads or only deltas
how often you refresh

A naive loop that fetches full event snapshots every few seconds can waste both data points and burst budget. Delta endpoints solve this by returning only what changed since your last request.

Shrink Every Response First

Before you tune polling intervals, make each response smaller.

curl -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"

Use these levers aggressively:

market_ids: biggest control for response size
affiliate_ids: only request the books you actually surface
main_line=true: skip alternate lines if your product only shows the primary market
event-specific endpoints: if you only care about a handful of games, do not fetch the full slate
hide_closed_markets=1: useful during market discovery to avoid off-board clutter

Delta Endpoint Bootstrap Flow

The pattern for using delta endpoints has three stages:

1. Fetch the full snapshot

Start by loading the complete event data for the sport and date you need. This gives you the initial state and the first delta cursor.

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

The response includes meta.delta_last_id — save this value.

2. Poll with the delta cursor

On each subsequent poll, pass your saved cursor to the delta endpoint. It returns only events or prices that changed since that cursor. Event delta — returns full event objects that changed:

curl "https://therundown.io/api/v2/delta?key=YOUR_API_KEY&last_id=PREVIOUS_DELTA_LAST_ID&sport_id=4"

Market delta — returns individual price changes (most efficient):

curl "https://therundown.io/api/v2/markets/delta?key=YOUR_API_KEY&last_id=0&sport_id=4&market_ids=1,2,3"

3. Merge updates into local state

Each delta response contains the full updated object — replace (do not partially merge) the corresponding entry in your local cache. Update your cursor to the new delta_last_id from the response.

Choosing Between Event and Market Delta

Endpoint	Returns	Best for
`GET /api/v2/delta`	Full event objects (scores, status, markets)	Apps that need score updates alongside odds
`GET /api/v2/markets/delta`	Individual price changes only	Odds-focused apps where you track scores separately

The market delta is usually the cheapest option because it returns only the specific prices that changed, rather than the entire event object.

Recommended Polling Intervals

Match your polling frequency to your use case. Faster polling uses more data points and increases the chance of hitting your burst limit if you parallelize heavily.

Use Case	Interval	Endpoint	Notes
Live odds screen	5–10s	Market delta	Fastest practical interval for REST
Pre-match odds monitoring	30–60s	Market delta	Lines move slowly before game time
Live scores	15–30s	Event delta	Score updates come in bursts during play
Pre-match schedules	5 min	Full events	Schedules rarely change close to game time
Historical/closing lines	On demand	Openers/closing	Fetch once after the event starts or ends

For sub-second updates, use the WebSocket endpoint on a WebSocket-enabled tier instead of polling. WebSocket traffic does not increment the HTTP request counter, but pushed messages are still metered as data points.

Cache TTL Recommendations

Not all data changes at the same rate. Cache aggressively for reference data and use shorter TTLs for live data.

Data Type	Recommended TTL	Endpoint
Sports list	24 hours	`GET /api/v2/sports`
Affiliates list	24 hours	`GET /api/v2/affiliates`
Teams	6 hours	`GET /api/v2/sports/{id}/teams`
Market definitions	6 hours	`GET /api/v2/markets`
Events (pre-match)	5 minutes	`GET /api/v2/sports/{id}/events/{date}`
Events (live)	Use delta	`GET /api/v2/delta` or `GET /api/v2/markets/delta`
Market prices	Real-time	Delta endpoint or WebSocket

Staleness Guards

Your delta cursor can become stale if you stop polling for an extended period. When this happens, the delta endpoint may return an error or skip events that changed while you were away. How to detect stale data:

Track the updated_at timestamp on your cached events. If the newest update is more than 5 minutes old during a live game window, your data may be stale.
If a delta response returns an empty result but you know games are in progress, your cursor may have expired.
If you receive an error response from the delta endpoint, re-bootstrap from a full snapshot.

How to recover:

Discard your current delta cursor
Fetch a fresh full snapshot from the events endpoint
Extract the new delta_last_id and resume polling

Watch Your Usage Headers

Every production poller should log and monitor:

X-Datapoints
X-Datapoints-Used
X-Datapoints-Remaining
X-Datapoints-Reset
X-Rate-Limit

That gives you the feedback loop to tune filters and polling intervals before users start hitting limits.

Code Example: Python Polling Loop

This example fetches a full snapshot, then polls the market delta endpoint with automatic fallback to a full refresh when the cursor goes stale.

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://therundown.io/api/v2"
SPORT_ID = 4
MARKET_IDS = "1,2,3"
AFFILIATE_IDS = "19,23"
POLL_INTERVAL = 5  # seconds

# Local cache: event_id -> event data
events = {}

def fetch_full_snapshot():
    """Load the full event list and return the delta cursor."""
    resp = requests.get(
        f"{BASE}/sports/{SPORT_ID}/events/2026-02-26",
        headers={"X-TheRundown-Key": API_KEY},
        params={
            "market_ids": MARKET_IDS,
            "affiliate_ids": AFFILIATE_IDS,
            "main_line": "true",
            "offset": "300",
        }
    )
    data = resp.json()

    for event in data.get("events", []):
        events[event["event_id"]] = event

    cursor = data.get("meta", {}).get("delta_last_id", "0")
    print(f"Loaded {len(events)} events, cursor={cursor}")
    return cursor

def poll_market_delta(last_id):
    """Fetch price changes since last_id. Returns new cursor."""
    resp = requests.get(
        f"{BASE}/markets/delta",
        headers={"X-TheRundown-Key": API_KEY},
        params={
            "last_id": last_id,
            "sport_id": SPORT_ID,
            "market_ids": MARKET_IDS,
        }
    )

    if resp.status_code != 200:
        print(f"Delta error {resp.status_code}, re-bootstrapping...")
        return None  # Signal to re-bootstrap

    data = resp.json()
    changes = data.get("deltas", [])

    for change in changes:
        eid = change.get("event_id")
        print(
            f"Price change: {eid} {change.get('market_name')} "
            f"{change.get('participant_name')} -> {change.get('price')}"
        )

    new_cursor = data.get("meta", {}).get("delta_last_id", last_id)
    return new_cursor

# Bootstrap
cursor = fetch_full_snapshot()

# Poll loop
while True:
    time.sleep(POLL_INTERVAL)
    result = poll_market_delta(cursor)

    if result is None:
        # Cursor went stale, re-bootstrap
        cursor = fetch_full_snapshot()
    else:
        cursor = result

WebSocket vs. Polling Decision Guide

Factor	REST Polling	WebSocket
Latency	5–60s depending on interval	Sub-second
Usage impact	Consumes data points and counts toward HTTP burst limit	Consumes data points but does not increment the HTTP request counter
Implementation complexity	Simple HTTP requests	Requires connection management, reconnection logic
Data freshness	As fresh as your poll interval	Real-time
Reliability	Each request is independent	Must handle disconnects and reconnections
Best for	Pre-match monitoring, low-frequency updates	Live odds screens, real-time dashboards

Many production applications use both: WebSocket for live windows, with delta polling as a fallback when the socket disconnects or for lower-tier keys that do not have WebSocket access. See the Building an Odds Screen guide for this pattern in practice.

Guides

​Why Polling Efficiency Matters

​Shrink Every Response First

​Delta Endpoint Bootstrap Flow

​1. Fetch the full snapshot

​2. Poll with the delta cursor

​3. Merge updates into local state

​Choosing Between Event and Market Delta

​Recommended Polling Intervals

​Cache TTL Recommendations

​Staleness Guards

​Watch Your Usage Headers

​Code Example: Python Polling Loop

​WebSocket vs. Polling Decision Guide

Why Polling Efficiency Matters

Shrink Every Response First

Delta Endpoint Bootstrap Flow

1. Fetch the full snapshot

2. Poll with the delta cursor

3. Merge updates into local state

Choosing Between Event and Market Delta

Recommended Polling Intervals

Cache TTL Recommendations

Staleness Guards

Watch Your Usage Headers

Code Example: Python Polling Loop

WebSocket vs. Polling Decision Guide