Python SDK - TheRundown API

An official Python SDK is coming soon. In the meantime, this guide shows how to use TheRundown API directly with the requests library for REST calls and websockets for real-time streaming.

Installation

pip install requests 'websockets>=14'

Configuration

import os

API_KEY = os.environ["THERUNDOWN_API_KEY"]
BASE_URL = "https://therundown.io/api/v2"
WS_URL = "wss://therundown.io/api/v2/ws/markets"

HEADERS = {
    "X-TheRundown-Key": API_KEY,
}
WS_HEADERS = HEADERS

Getting Sports

import requests

response = requests.get(f"{BASE_URL}/sports", headers=HEADERS)
response.raise_for_status()

sports = response.json()["sports"]
for sport in sports:
    print(f"{sport['sport_id']}: {sport['sport_name']}")

Getting Events with Odds

import requests
from datetime import date

sport_id = 4  # NBA
today = date.today().isoformat()

response = requests.get(
    f"{BASE_URL}/sports/{sport_id}/events/{today}",
    headers=HEADERS,
    params={
        "market_ids": "1,2,3",      # Moneyline, Spread, Total
        "affiliate_ids": "19,23",    # DraftKings, FanDuel
        "main_line": "true",
    }
)
response.raise_for_status()
data = response.json()

for event in data["events"]:
    away = event["teams"][0]["name"]
    home = event["teams"][1]["name"]
    print(f"\n{away} @ {home}")

    for market in event.get("markets", []):
        print(f"  {market['name']}:")
        for participant in market["participants"]:
            for line in participant["lines"]:
                for aff_id, price in line["prices"].items():
                    p = price["price"]
                    display = "N/A" if p == 0.0001 else f"{p:+d}" if p > 0 else str(int(p))
                    line_val = f" ({line['value']})" if line.get("value") else ""
                    print(f"    {participant['name']}{line_val}: {display} @ {aff_id}")

Filtering by Affiliate

# Only DraftKings lines
response = requests.get(
    f"{BASE_URL}/sports/4/events/{date.today()}",
    headers=HEADERS,
    params={
        "market_ids": "1,2,3",
        "affiliate_ids": "19",  # DraftKings only
        "main_line": "true",
    }
)

Getting Player Props

# NBA player points, rebounds, assists, 3PT
response = requests.get(
    f"{BASE_URL}/sports/4/events/{date.today()}",
    headers=HEADERS,
    params={
        "market_ids": "29,35,38,39",  # Points, Rebounds, 3PT, Assists
        "affiliate_ids": "19",
    }
)
response.raise_for_status()

for event in response.json()["events"]:
    print(f"\n{event['teams'][0]['name']} @ {event['teams'][1]['name']}")
    for market in event.get("markets", []):
        print(f"  {market['name']}:")
        for participant in market["participants"]:
            for line in participant["lines"]:
                price = line["prices"].get("19", {}).get("price", "N/A")
                print(f"    {participant['name']}: {line.get('value')} ({price})")

Stats: sample first, then one completed event

The fixed sample is a zero-data-point schema check. For production stats, request one known completed event with a small stats_ids filter, cache the response, and fetch again only when your product needs a correction. Do not turn this into a per-team polling loop.

# Static sample: authenticate it, but do not poll it.
sample = requests.get(f"{BASE_URL}/stats/sample", headers=HEADERS)
sample.raise_for_status()
print(sample.json()["sample"], sample.json()["event"]["event_id"])

# Production: one completed MLB event and three example catalog fields only.
# Discover current IDs with GET /stats?sport_id=3; do not hard-code these IDs.
event_id = "e241d4b4967e3bc003cdc2f77666bb82"
team_box = requests.get(
    f"{BASE_URL}/events/{event_id}/stats",
    headers=HEADERS,
    params={"stats_ids": "271,273,276"},  # hits, home runs, runs
)
team_box.raise_for_status()

The production call requires access to that event’s current season. It becomes archive access after the season changes. The IDs shown are examples only: for your own request, get the event ID from the current events route and discover current supported IDs from GET /stats?sport_id=3 before filtering. Production routes depend on effective stats access. See Stats Access.

Historical Odds

event_id = "abc123"

# Full market history
response = requests.get(
    f"{BASE_URL}/events/{event_id}/markets/history",
    headers=HEADERS,
    params={"affiliate_ids": "19"},
)
history = response.json()["history"]

for entry in history:
    print(f"{entry['updated_at']}: line={entry['line']} price={entry['price']} ({entry['change_type']})")

# Opening lines
openers = requests.get(
    f"{BASE_URL}/events/{event_id}/openers",
    headers=HEADERS,
    params={"market_ids": "1,2,3"},
).json()

# Closing lines
closing = requests.get(
    f"{BASE_URL}/events/{event_id}/closing",
    headers=HEADERS,
    params={"market_ids": "1,2,3"},
).json()

WebSocket Streaming

import asyncio
import json
import websockets


async def stream_odds(sport_ids="4", market_ids="1,2,3"):
    url = (
        f"{WS_URL}?sport_ids={sport_ids}"
        f"&market_ids={market_ids}"
    )

    async with websockets.connect(url, additional_headers=WS_HEADERS) as ws:
        print("Connected to WebSocket")

        async for message in ws:
            msg = json.loads(message)

            if msg.get("meta", {}).get("type") != "market_price":
                continue

            d = msg["data"]
            print(
                f"Update: event={d['event_id']} market={d['market_id']}"
                f" aff={d['affiliate_id']} price={d['price']}"
            )


asyncio.run(stream_odds())

WebSocket with Reconnection

import asyncio
import json
import random
import websockets


async def stream_with_reconnect(sport_ids="4", market_ids="1,2,3"):
    url = (
        f"{WS_URL}?sport_ids={sport_ids}"
        f"&market_ids={market_ids}"
    )

    reconnect_delay = 1.0
    max_delay = 30.0

    while True:
        try:
            async with websockets.connect(url, additional_headers=WS_HEADERS) as ws:
                print("WebSocket connected")
                reconnect_delay = 1.0

                async for message in ws:
                    msg = json.loads(message)
                    if msg.get("meta", {}).get("type") != "market_price":
                        continue

                    # Process update
                    d = msg["data"]
                    print(f"Update: event={d['event_id']} market={d['market_id']} price={d['price']}")

        except (websockets.ConnectionClosed, ConnectionError) as e:
            jitter = random.uniform(0, 1)
            delay = min(reconnect_delay + jitter, max_delay)
            print(f"Disconnected ({e}). Reconnecting in {delay:.1f}s...")
            await asyncio.sleep(delay)
            reconnect_delay = min(reconnect_delay * 2, max_delay)


asyncio.run(stream_with_reconnect())

Error Handling

import requests
import time


def api_get(path, params=None, max_retries=3):
    """Make an API request with retry logic for rate limits."""
    for attempt in range(max_retries):
        response = requests.get(
            f"{BASE_URL}{path}",
            headers=HEADERS,
            params=params,
        )

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited. Retrying in {wait:.1f}s...")
            time.sleep(wait)
            continue

        response.raise_for_status()

    raise Exception("Max retries exceeded")


# Usage
data = api_get(
    f"/sports/4/events/{date.today()}",
    params={"market_ids": "1,2,3"},
)

Next Steps

Getting Live Odds

Detailed guide on fetching odds

WebSocket Streaming

Real-time data streaming guide

Authentication

All authentication methods

Rate Limits

Rate limit details and best practices

​Installation

​Configuration

​Getting Sports

​Getting Events with Odds

​Filtering by Affiliate

​Getting Player Props

​Stats: sample first, then one completed event

​Historical Odds

​WebSocket Streaming

​WebSocket with Reconnection

​Error Handling

​Next Steps

Getting Live Odds

WebSocket Streaming

Authentication

Rate Limits

Installation

Configuration

Getting Sports

Getting Events with Odds

Filtering by Affiliate

Getting Player Props

Stats: sample first, then one completed event

Historical Odds

WebSocket Streaming

WebSocket with Reconnection

Error Handling

Next Steps