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.

TODAY_UTC=$(date -u +%F)

curl -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
  "https://therundown.io/api/v2/sports/3/events/$TODAY_UTC?market_ids=1,2,3,41,42,43&affiliate_ids=19,23&main_line=true"

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.

TODAY_UTC=$(date -u +%F)

curl -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" "https://therundown.io/api/v2/sports/3/events/$TODAY_UTC?market_ids=1,2,3,41,42,43&affiliate_ids=19,23&main_line=true"

For a plan with explicitly confirmed zero data delay, the response body’s meta.delta_last_id is the canonical bootstrap cursor for /api/v2/markets/delta. Accept a positive integer whether encoded as a number or string. Never replace a missing or invalid cursor with 0.

Delayed plans use narrow, repeated event snapshots and never bootstrap market-delta polling from a delayed snapshot. A missing or invalid X-Data-Delay-Seconds header means the delay is unknown, not zero. Use delta polling only when a known plan entitlement establishes zero delay; a positive server-reported delay always rules out delta polling.

2. Poll the market delta endpoint

On each subsequent poll, pass your saved cursor to /api/v2/markets/delta. It returns only the prices that changed since that cursor — the most efficient way to keep odds fresh. Use the same explicit full-game core scope in the snapshot and delta request: 1,2,3,41,42,43. Market delta filters IDs literally, and delta rows retain their actual market IDs. For soccer, NHL regulation-time, tennis, and futures scopes, use the sport-aware recommended core market scopes.

curl -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" "https://therundown.io/api/v2/markets/delta?last_id=PREVIOUS_DELTA_LAST_ID&sport_id=3&market_ids=1,2,3,41,42,43&affiliate_ids=19,23"

Each response includes its own meta.delta_last_id (also an integer) — use that as last_id on the next poll. Do not bootstrap with last_id=0: a cursor that has fallen too far behind the current head is rejected, so always seed from a fresh, zero-delay events snapshot.

The two delta endpoints take different, non-interchangeable cursors:

/api/v2/markets/delta (price changes) uses an integer cursor. On known zero-delay access, bootstrap it from the events snapshot’s integer meta.delta_last_id, then follow the integer cursor in each markets-delta response. This is the endpoint for odds polling.
/api/v2/delta (full event-object changes: status, scores, the whole event) uses an ordered UUID cursor, e.g. 11f1-23b3-f4d42784-8057-a3a997572248. That cursor is only returned by /api/v2/delta’s own responses — the events snapshot does not provide it.

Passing the integer events cursor to /api/v2/delta returns a 400. For price and odds polling, use /api/v2/markets/delta.

3. Merge updates into local state

Each delta response contains changed price rows. Upsert each row by its exact event, market, participant, participant type, normalized line, and affiliate identity; remove rows whose closed_at is present; and retain the returned is_main_line value. Update your cursor to the new delta_last_id from the response. Market delta is scoped by sport, not date. Ignore a delta row whose event_id is absent from your latest snapshot, and use the next snapshot to refresh event membership and schedule metadata.

Polling futures too? The futures snapshot (GET /api/v2/sports/{sportID}/futures) provides the same meta.delta_last_id bootstrap cursor, but futures market IDs are not in the delta feed’s default set — pass them explicitly (e.g. market_ids=1141). See the Futures guide.

Choosing Between Event and Market Delta

Endpoint	Returns	Cursor type	Bootstrap source	Best for
`GET /api/v2/markets/delta`	Individual price changes only	Integer	Events snapshot `meta.delta_last_id`	Odds-focused apps (recommended for price polling)
`GET /api/v2/delta`	Full event objects (scores, status, markets)	Ordered UUID	The endpoint’s own response `meta.delta_last_id`	Apps that need full event-object changes alongside odds

The market delta is usually the cheapest option because it returns only the specific prices that changed, rather than the entire event object. The cursors are not interchangeable — the integer from the events snapshot bootstraps markets/delta only, and /api/v2/delta rejects it with a 400.

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	Known zero-delay access only
Pre-match odds monitoring	30–60s	Market delta or narrow snapshots	Use snapshots on delayed or unknown access
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

On a WebSocket-enabled tier, use the WebSocket endpoint instead of polling when you need sub-second odds updates across every book or play and game-stat updates at play latency. For supported live games, live data trails the on-field action by roughly 15–20 seconds, in line with the typical broadcast delay. 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.
An empty delta response can mean that no matching prices changed; it does not by itself indicate a stale cursor.
A 400 cursor error can require one fresh snapshot bootstrap on known zero-delay access. Stop on authentication, entitlement, or rate-limit responses and handle them through your scheduler or account flow.

How to recover:

On one cursor error, fetch one fresh full snapshot from the events endpoint
On known zero-delay access, extract its valid delta_last_id and resume polling
If the next delta response still has a cursor error, stop and investigate; do not loop re-bootstrap requests

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 bounded example uses market delta only when a known entitlement establishes zero delay. Delayed or unknown access repeats narrow snapshots instead. It is intentionally finite so callers can apply their own scheduler, retry policy, and alerting.

import os
import requests
import time
from datetime import datetime, timezone
from decimal import Decimal, InvalidOperation

API_KEY = os.environ["THERUNDOWN_API_KEY"]
BASE = "https://therundown.io/api/v2"
SPORT_ID = 3  # MLB
SNAPSHOT_MARKET_IDS = "1,2,3,41,42,43"
DELTA_MARKET_IDS = "1,2,3,41,42,43"
CORE_MARKET_ID_SET = frozenset(DELTA_MARKET_IDS.split(","))
AFFILIATE_IDS = "19,23"
REQUEST_TIMEOUT = 10
POLL_INTERVAL = 5
SNAPSHOT_INTERVAL = 60
MAX_CYCLES = 12
MAX_DELTA_PAGES = 3
# Set only from a known entitlement. Do not infer it from a missing header.
KNOWN_ZERO_DELAY_ENTITLEMENT = False

events = {}
prices = {}

def positive_cursor(value):
    if isinstance(value, bool):
        return None
    if isinstance(value, int) and value > 0:
        return str(value)
    if isinstance(value, str) and value.isdigit() and int(value) > 0:
        return str(int(value))
    return None

def normalized_line(value):
    if value is None or value == "":
        value = 0  # A moneyline may omit its snapshot line value.
    if isinstance(value, bool):
        return None
    try:
        line = Decimal(str(value))
    except (InvalidOperation, ValueError):
        return None
    if not line.is_finite():
        return None
    if line == 0:
        return "0"  # Treat 0 and -0 as the same moneyline identity.
    return format(line.normalize(), "f")

def row_key(row):
    fields = ("event_id", "market_id", "participant_id", "participant_type", "affiliate_id")
    values = tuple(row.get(field) for field in fields)
    line = normalized_line(row.get("line"))
    if not all(value is not None for value in values) or line is None:
        return None
    event_id, market_id, participant_id, participant_type, affiliate_id = values
    return (str(event_id), str(market_id), str(participant_id), str(participant_type), line, str(affiliate_id))

def apply_price(row):
    if str(row.get("event_id")) not in events:
        return  # The delta stream can include another date's event.
    if str(row.get("market_id")) not in CORE_MARKET_ID_SET:
        return  # Keep this core-odds cache within its requested market scope.
    key = row_key(row)
    if key is None:
        return
    if row.get("closed_at"):
        prices.pop(key, None)
    else:
        # Replacing the complete row applies both price and is_main_line changes.
        prices[key] = row

def load_snapshot_prices(event):
    for market in event.get("markets", []):
        for participant in market.get("participants", []):
            for line in participant.get("lines", []):
                for affiliate_id, price in line.get("prices", {}).items():
                    apply_price({
                        **price,
                        "event_id": event.get("event_id"),
                        "market_id": market.get("market_id"),
                        "participant_id": participant.get("id"),
                        "participant_type": participant.get("type"),
                        "line": line.get("value", 0),
                        "affiliate_id": affiliate_id,
                    })

def snapshot_allows_delta(resp):
    raw_delay = resp.headers.get("X-Data-Delay-Seconds")
    if raw_delay is None:
        return False
    try:
        delay_seconds = int(raw_delay)
    except ValueError:
        return False
    return delay_seconds == 0 and KNOWN_ZERO_DELAY_ENTITLEMENT

def fetch_full_snapshot():
    """Load one narrow UTC-day snapshot and return its valid cursor, if any."""
    today_utc = datetime.now(timezone.utc).date().isoformat()
    resp = requests.get(
        f"{BASE}/sports/{SPORT_ID}/events/{today_utc}",
        headers={"X-TheRundown-Key": API_KEY},
        params={
            "market_ids": SNAPSHOT_MARKET_IDS,
            "affiliate_ids": AFFILIATE_IDS,
            "main_line": "true",
        },
        timeout=REQUEST_TIMEOUT,
    )
    if resp.status_code in (401, 403, 429):
        return None, False, resp.status_code
    resp.raise_for_status()
    data = resp.json()

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

    cursor = positive_cursor(data.get("meta", {}).get("delta_last_id"))
    print(f"Loaded {len(events)} events, cursor={cursor}")
    return cursor, snapshot_allows_delta(resp), 200

def poll_market_delta(last_id):
    """Apply up to MAX_DELTA_PAGES and return a cursor or a stop reason."""
    cursor = last_id
    for _ in range(MAX_DELTA_PAGES):
        resp = requests.get(
            f"{BASE}/markets/delta",
            headers={"X-TheRundown-Key": API_KEY},
            params={
                "last_id": cursor,
                "sport_id": SPORT_ID,
                "market_ids": DELTA_MARKET_IDS,
                "affiliate_ids": AFFILIATE_IDS,
            },
            timeout=REQUEST_TIMEOUT,
        )
        if resp.status_code in (401, 403):
            return None, "authorization_or_entitlement"
        if resp.status_code == 429:
            return None, "rate_limited"
        if resp.status_code == 400:
            return None, "cursor_error"
        resp.raise_for_status()
        data = resp.json()
        for change in data.get("deltas", []):
            apply_price(change)
        next_cursor = positive_cursor(data.get("meta", {}).get("delta_last_id"))
        if not next_cursor:
            return None, "invalid_cursor"
        cursor = next_cursor
        if not data.get("meta", {}).get("has_more"):
            return cursor, None
    return None, "page_limit"

cursor, use_delta, status = fetch_full_snapshot()
if status in (401, 403, 429):
    raise RuntimeError(f"Snapshot stopped with HTTP {status}")

if not use_delta:
    for _ in range(MAX_CYCLES):
        time.sleep(SNAPSHOT_INTERVAL)
        _, _, status = fetch_full_snapshot()
        if status in (401, 403, 429):
            break
elif not cursor:
    raise RuntimeError("Zero-delay snapshot did not provide a valid cursor")
else:
    rebootstrap_used = False
    for _ in range(MAX_CYCLES):
        time.sleep(POLL_INTERVAL)
        cursor, reason = poll_market_delta(cursor)
        if reason in ("authorization_or_entitlement", "rate_limited", "page_limit"):
            break
        if reason and not rebootstrap_used:
            rebootstrap_used = True
            cursor, use_delta, status = fetch_full_snapshot()
            if not use_delta or not cursor or status != 200:
                break
        elif reason:
            break

WebSocket vs. Polling Decision Guide

Factor	REST Polling	WebSocket
Latency	5–60s depending on interval	Real-time odds updates are sub-second across every book. Supported live game stats stream within seconds of corresponding play updates (~15–20s behind on-field action)
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.

​Why Polling Efficiency Matters

​Shrink Every Response First

​Delta Endpoint Bootstrap Flow

​1. Fetch the full snapshot

​2. Poll the market delta endpoint

​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 the market delta endpoint

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