Skip to main content
This guide walks through fetching current odds for a sport, understanding the response structure, and filtering by sportsbook and market type.

​
Fetching Events with Odds

The primary endpoint for odds data is: 
GET /api/v2/sports/{sportID}/events/{date}
Use the market_ids parameter to specify which market types to include. The three core markets are:
MarketIDDescription
Moneyline1Who wins the game
Point Spread2Handicap / spread
Total (Over/Under)3Combined score
Always include offset=300 to align the date boundary with US Central Time. Without it, games starting late at night may appear under the wrong date. The offset is in minutes (300 = 5 hours).
curl "https://therundown.io/api/v2/sports/4/events/2026-02-12?key=YOUR_API_KEY&market_ids=1,2,3&offset=300"

​
Understanding the Response Structure

The V2 response follows a nested hierarchy: 
event
  ├── score                        # Live status, clock, and current score
  └── markets[]                    # Array of market types (moneyline, spread, total, etc.)
        ├── market_id              # Numeric market identifier
        ├── name                   # Human-readable market name
        └── participants[]         # Teams or players in this market
              ├── id               # Unique participant identifier
              ├── type             # "TYPE_TEAM", "TYPE_PLAYER", or "TYPE_RESULT"
              ├── name             # Participant name (team or player)
              └── lines[]          # Available lines for this participant
                    ├── value      # Line value (e.g., "-3.5" for spread, empty for moneyline)
                    └── prices{}   # Map of affiliate_id → price object
                          ├── price        # American odds (e.g., -110, +150)
                          ├── is_main_line # Whether this is the primary line
                          └── updated_at   # When this price was last updated
Here is a condensed example response for a single event: 
{
  "events": [
    {
      "event_id": "abc123",
      "sport_id": 4,
      "score": {
        "event_status": "STATUS_IN_PROGRESS",
        "score_away": 62,
        "score_home": 55,
        "display_clock": "4:32",
        "game_period": 2,
        "event_status_detail": "4:32 - 2nd",
        "updated_at": "2026-02-12T18:30:00Z"
      },
      "teams": [
        { "team_id": 1, "name": "Boston Celtics" },
        { "team_id": 2, "name": "Los Angeles Lakers" }
      ],
      "markets": [
        {
          "market_id": 1,
          "name": "Moneyline",
          "period_id": 0,
          "participants": [
            {
              "id": 1,
              "type": "TYPE_TEAM",
              "name": "Boston Celtics",
              "lines": [
                {
                  "value": "",
                  "prices": {
                    "19": { "price": -150, "is_main_line": true, "updated_at": "2026-02-12T18:30:00Z" },
                    "23": { "price": -145, "is_main_line": true, "updated_at": "2026-02-12T18:28:00Z" }
                  }
                }
              ]
            },
            {
              "id": 2,
              "type": "TYPE_TEAM",
              "name": "Los Angeles Lakers",
              "lines": [
                {
                  "value": "",
                  "prices": {
                    "19": { "price": 130, "is_main_line": true, "updated_at": "2026-02-12T18:30:00Z" },
                    "23": { "price": 125, "is_main_line": true, "updated_at": "2026-02-12T18:28:00Z" }
                  }
                }
              ]
            }
          ]
        },
        {
          "market_id": 2,
          "name": "Point Spread",
          "period_id": 0,
          "participants": [
            {
              "id": 1,
              "type": "TYPE_TEAM",
              "name": "Boston Celtics",
              "lines": [
                {
                  "value": "-3.5",
                  "prices": {
                    "19": { "price": -110, "is_main_line": true, "updated_at": "2026-02-12T18:30:00Z" }
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
Use score.event_status to identify live games, score.display_clock and score.game_period for the on-screen state, and score.updated_at to judge freshness. Some live score metadata, especially venue_name and venue_location, may be empty strings until the upstream feed provides them.

​
Filtering by Sportsbook

Use the affiliate_ids parameter to limit results to specific sportsbooks. This reduces payload size and focuses on the books you care about. 
# Only DraftKings (19) and FanDuel (23)
curl "https://therundown.io/api/v2/sports/4/events/2026-02-12?\
key=YOUR_API_KEY&market_ids=1,2,3&affiliate_ids=19,23&offset=300"
Common affiliate IDs:
SportsbookID
DraftKings19
FanDuel23
BetMGM22
ESPN Bet24
Pinnacle3
See Sportsbook IDs for the full list.

​
Main Lines vs. Alternates

By default, the API returns both main lines and alternate lines. Alternate lines are additional spread/total values offered by sportsbooks (e.g., -2.5, -3.0, -3.5, -4.0 for a spread market). To fetch only the primary line for each market, add main_line=true: 
curl "https://therundown.io/api/v2/sports/4/events/2026-02-12?\
key=YOUR_API_KEY&market_ids=1,2,3&main_line=true&offset=300"
When main_line=true is set, each participant will have at most one line object per market, and the is_main_line field on each price will be true. This is recommended for odds screens where you only need the consensus line.

​
Handling the 0.0001 Sentinel Value

A price value of 0.0001 means the line is off the board — the sportsbook has temporarily removed it. This commonly happens when:
  • A key injury is being evaluated
  • The book is recalculating after sharp action
  • The market is approaching game time suspension
Never display 0.0001 to end users or use it in calculations. Show “Off Board” or “N/A” instead.
def format_price(price_value):
    """Format a price for display, handling sentinel values."""
    if price_value == 0.0001:
        return "Off Board"
    if price_value > 0:
        return f"+{int(price_value)}"
    return str(int(price_value))


# Usage
for event in data["events"]:
    for market in event.get("markets", []):
        for participant in market["participants"]:
            for line in participant["lines"]:
                for aff_id, price_obj in line["prices"].items():
                    display = format_price(price_obj["price"])
                    print(f"{participant['name']}: {display}")

​
Full Working Example

Here is a complete example that fetches NBA odds, filters to DraftKings and FanDuel, and prints a formatted table: 
import requests
from datetime import date

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://therundown.io/api/v2"
BOOKS = {"19": "DraftKings", "23": "FanDuel"}

response = requests.get(
    f"{BASE_URL}/sports/4/events/{date.today()}",
    params={
        "key": API_KEY,
        "market_ids": "1,2,3",
        "affiliate_ids": "19,23",
        "main_line": "true",
        "offset": "300",  # Central Time
    }
)
data = response.json()


def fmt(price):
    if price == 0.0001:
        return "N/A"
    return f"+{int(price)}" if price > 0 else str(int(price))


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

    for market in event.get("markets", []):
        print(f"\n  {market['name']}:")
        for participant in market["participants"]:
            for line in participant["lines"]:
                line_str = f" ({line['value']})" if line.get("value") else ""
                prices_str = "  ".join(
                    f"{BOOKS.get(aid, aid)}: {fmt(p['price'])}"
                    for aid, p in line["prices"].items()
                )
                print(f"    {participant['name']}{line_str}: {prices_str}")

​
Next Steps

Building an Odds Screen

Turn this data into a full UI

WebSocket Streaming

Get real-time updates instead of polling

Efficient Polling

Delta endpoints, cache TTLs, and polling intervals

Data Model

How events, markets, lines, and prices relate

Historical Odds

Track line movement over time

Market IDs Reference

All available market types