1. Home
  2. Blog
  3. Developer guide

Developer guide

Moneyline odds API: spreads and totals in JSON

Moneyline, spread and total odds from 25+ books in JSON: the fields each market returns, curl and Python requests, and what Free and paid plans include.

· 8 min read

TheRundown’s sports odds API returns live and historical sportsbook prices as structured JSON, organized from each sports event down to the exact price each book is offering. This matters because odds live in a hierarchy (one event can carry dozens of markets, and each market has a price per sportsbook that changes throughout the day), so a useful client has to model that hierarchy, not just fetch a flat list of numbers. This guide covers the data model, authentication, a first request in curl and Python, how moneyline, spread and total odds look in the response, how to pick sports, markets, and books by ID, and how plans differ on freshness and coverage.

To build a scoreboard, follow the Python sports scores guide for a request without sportsbook prices and examples of team identity, zero scores, status and game clocks.

The data model: events, markets, participants, lines, prices

Every response follows the same nesting, from broadest to most specific:

  • Event: a single game or match (for example, one NFL game on a given Sunday).
  • Market: a type of bet on that event (moneyline, spread, total, or a player prop).
  • Participant: one side of the market (a team, or a player for a prop).
  • Line: the specific number attached to a participant (a spread of −3.5, a total of 44.5).
  • Price: what a given sportsbook is charging for that line, keyed by sportsbook (affiliate) ID. Each price object includes price (American odds, such as −110 or +150) and updated_at, the timestamp of the last change.

Walking down that chain (event, then markets, then participants, then lines, then prices) is the core loop of almost any integration, whether you are building an odds table, a line-shopping tool, or an alert on price moves.

Authenticating requests

The base URL is https://therundown.io/api/v2. Every request needs your API key in the X-TheRundown-Key header:

curl --fail-with-body --silent --show-error "https://therundown.io/api/v2/affiliates" \
  -H "X-TheRundown-Key: $THERUNDOWN_API_KEY"

Get a free key on the odds API page. Keep it in an environment variable (THERUNDOWN_API_KEY in the examples below) rather than committing it to source control.

Your first request

Fetching a slate of odds is normally a two-step process: find a date that has games, then pull that date’s events with the markets and books you want.

Step 1: find dates with games

Game schedules are not evenly spaced, so start by asking which dates have games. For the NFL, pass all three season types together as sport_ids: regular season is 2, preseason is 25, and playoffs is 26. Add exclude_canceled=true so a day whose only events are canceled does not count as the next game date:

curl --fail-with-body --silent --show-error "https://therundown.io/api/v2/sports/dates?sport_ids=2,25,26&format=epoch&exclude_canceled=true" \
  -H "X-TheRundown-Key: $THERUNDOWN_API_KEY"

Step 2: pull the slate

Take one of the dates from that response and request the events for it, narrowed to the markets and sportsbooks you care about. This example asks for moneyline, spread, and total (market_ids=1,2,3) from DraftKings, BetMGM, and FanDuel (affiliate_ids=19,22,23), limited to the main line with main_line=true:

curl --fail-with-body --silent --show-error "https://therundown.io/api/v2/sports/2/events/2026-10-12?market_ids=1,2,3&affiliate_ids=19,22,23&main_line=true" \
  -H "X-TheRundown-Key: $THERUNDOWN_API_KEY"

Replace 2026-10-12 with a date returned by the first call.

Doing it in Python

The same two calls with requests: pick the soonest upcoming date across the three NFL season types, pull that slate, and walk the nested response. The pause respects Free’s one-request-per-second limit. Check each response for HTTP errors before reading its JSON so an authentication or rate-limit error is not mistaken for an empty slate.

import os
import time
from datetime import datetime, timezone

import requests

api = "https://therundown.io/api/v2"
headers = {"X-TheRundown-Key": os.environ["THERUNDOWN_API_KEY"]}

# Step 1: the next NFL game date (regular season, preseason, or playoffs)
dates_resp = requests.get(
    f"{api}/sports/dates",
    params={"sport_ids": "2,25,26", "format": "epoch", "exclude_canceled": "true"},
    headers=headers,
    timeout=30,
)
dates_resp.raise_for_status()
dates = dates_resp.json()
now = datetime.now(timezone.utc).timestamp()
upcoming = [
    (sport_id, stamp)
    for sport_id, body in dates.items()
    for stamp in body.get("dates") or []
    if stamp > now
]
sport_id, stamp = min(upcoming, key=lambda row: row[1], default=("2", now))
date = datetime.fromtimestamp(stamp, timezone.utc).date().isoformat()

# Step 2: that slate's moneyline, spread, and total from three books
time.sleep(1.1)  # Space these sequential requests for Free's 1 req/sec limit.
slate_resp = requests.get(
    f"{api}/sports/{sport_id}/events/{date}",
    params={"market_ids": "1,2,3", "affiliate_ids": "19,22,23", "main_line": "true"},
    headers=headers,
    timeout=30,
)
slate_resp.raise_for_status()
slate = slate_resp.json()

# Walk the data model: events, markets, participants, lines, prices
for event in slate.get("events") or []:
    for market in event["markets"]:
        for participant in market["participants"]:
            for line in participant["lines"]:
                for affiliate_id, price in line["prices"].items():
                    print(event["event_id"], market["market_id"], participant["name"],
                          affiliate_id, price["price"], price["updated_at"])

Moneyline, spread and total odds in the response

Moneyline, spread and total are market IDs 1, 2 and 3, and all three share the same shape. What changes is who the participants are and whether a line carries a number. Each market also has a period_id, where 0 is the full game.

Moneyline (market_id 1) Spread (market_id 2) Total (market_id 3)
name moneyline handicap totals
Participants Each team (TYPE_TEAM) Each team (TYPE_TEAM) Over and Under (TYPE_RESULT)
value (line) None: a moneyline has no number Each team’s spread as a signed string, such as -11.5 and +11.5 The total as a string, such as 221.5, on both sides
price American odds, such as -550 and +410 Such as -115 and -105 Such as -105 and -115

Each price sits under its sportsbook (affiliate) ID and carries:

  • price: American odds.
  • price_delta: the change from that book’s previous price, present when the price has moved.
  • is_main_line: true for the book’s main line. Alternate spreads and totals come back as false when you leave out main_line=true.
  • updated_at: when that book last changed the price.

Books do not always hang the same number. With main_line=true, a total can come back as two lines, such as 221.5 from one book and 222.5 from another, and each line lists only the books offering that number. Compare books on the same value before comparing prices.

Here is the moneyline market for one NBA game (sport ID 4, requested the same way as Step 2), trimmed to FanDuel (23):

{
  "market_id": 1,
  "period_id": 0,
  "name": "moneyline",
  "participants": [
    {
      "name": "Boston Celtics",
      "type": "TYPE_TEAM",
      "lines": [
        {
          "prices": {
            "23": {
              "price": -550,
              "price_delta": 40,
              "is_main_line": true,
              "updated_at": "2026-10-27T12:54:15Z"
            }
          }
        }
      ]
    },
    {
      "name": "Brooklyn Nets",
      "type": "TYPE_TEAM",
      "lines": [
        {
          "prices": {
            "23": {
              "price": 410,
              "price_delta": -20,
              "is_main_line": true,
              "updated_at": "2026-10-27T12:54:15Z"
            }
          }
        }
      ]
    }
  ]
}

A spread or total line adds its number as value. The same game’s FanDuel spread for Boston:

{
  "value": "-11.5",
  "prices": {
    "23": {
      "price": -115,
      "is_main_line": true,
      "updated_at": "2026-10-27T01:52:31Z"
    }
  }
}

Player props and team totals use the same shape under their own market IDs (see the table below). Start with a free sports odds API key: Free returns pre-match moneyline, spread and total odds from DraftKings, FanDuel and BetMGM.

Compare open sportsbook prices in Python

To compare prices, keep the event, market, period, participant and exact signed line together. Buffalo at −3 and Baltimore at +3 are different selections; Buffalo at −3 and Buffalo at −3.5 are different rungs. The API already groups each line’s prices by sportsbook, so compare inside that prices object.

Use closed_at to decide whether a quote is available. A nonempty timestamp means closed. An omitted or empty field means open, including a reopened quote. An old updated_at does not make a price closed, and a recent timestamp does not make a closed price available. The special price 0.0001 means off the board and is also excluded.

After the Python request above, this function compares DraftKings (19) and FanDuel (23) in slate. It keeps ties and leaves each signed line and participant intact. Prediction markets and exchanges should stay separate from sportsbook best-price comparisons; this example selects only these two sportsbooks.

def compare_open_lines(slate):
    def decimal_odds(price):
        return 1 + price / 100 if price > 0 else 1 + 100 / abs(price)

    for event in slate.get("events", []):
        for market in event.get("markets", []):
            for participant in market.get("participants", []):
                for line in participant.get("lines", []):
                    prices = {
                        book: quote["price"]
                        for book, quote in line.get("prices", {}).items()
                        if book in ("19", "23")
                        and not quote.get("closed_at")
                        and quote["price"] not in (0, 0.0001)
                    }
                    if not prices:
                        continue
                    best = max(decimal_odds(price) for price in prices.values())
                    yield {
                        "event_id": event["event_id"],
                        "market_id": market["market_id"],
                        "period_id": market.get("period_id"),
                        "participant_id": participant["id"],
                        "participant_type": participant["type"],
                        "participant": participant["name"],
                        "line_value": line.get("value"),
                        "prices": prices,
                        "best_affiliate_ids": [
                            book for book, price in prices.items()
                            if decimal_odds(price) == best
                        ],
                    }

for row in compare_open_lines(slate):
    print(row)

A moneyline has no line value, so line_value is None for that row. Over and Under retain their separate participant IDs. A row with no available quote from either selected book is omitted. With main_line=true, one book can post a different main spread or total from the other; those stay as separate rows. To compare posted alternates too, omit main_line=true from the request and keep the same grouping.

For the field contract and closing/reopening examples, see the Price object reference.

Choosing sports, markets, and sportsbooks by ID

Requests filter by numeric IDs rather than names. The common ones:

Sport IDs

ID Sport
1 NCAAF
2 NFL
3 MLB
4 NBA
5 NCAAB
6 NHL
7 UFC/MMA
8 WNBA
10 MLS
11 EPL

Market IDs

ID Market
1 Moneyline
2 Spread
3 Total
29 Player points
35 Player rebounds
39 Player assists
94 Team totals

Sportsbook (affiliate) IDs

ID Sportsbook
3 Pinnacle
19 DraftKings
22 BetMGM
23 FanDuel
25 Kalshi
26 Polymarket

These six are the ones you will reach for most, but the API currently covers 25+ books. Get the full, current list with GET /api/v2/affiliates, no key required.

Keeping prices fresh: polling vs. WebSocket

REST works on every plan, within its data-point allowance. Prices on each plan trail the market by a fixed delay: five minutes on Free, 60 seconds on Starter, and 30 seconds on Pro. Polling more often shows changes sooner, but never closer to real time than that delay, and every response counts against your data points (the X-Datapoints response header shows how many a request used).

Ultra and the plans above it add a WebSocket feed that pushes price changes as they happen, with one concurrent connection on Ultra. If you need true real-time odds for a live betting product, a trading or hedging tool, or a price-move alerting system, the WebSocket feed on Ultra and up is the right tool. If your use case is slower, such as a daily odds table or an overnight research pipeline, polling REST within your plan’s delay is simpler and is all you need.

For the exact delay and data-point numbers, a decision table, and a streaming Python client, see Sports odds WebSocket API vs. REST polling.

Free vs. paid plans

Prices and limits below are current as of October 2026; see API pricing for the live numbers.

Plan Price Data points Delay History WebSocket Notes
Free $0, no card 20,000/day (200,000/month) 5 min None No Pre-match moneyline, spread, total from DraftKings, FanDuel, BetMGM only
Starter $69/month 25,000,000/month 60 sec 7 days No Every published book, market, and period; internal/personal use
Pro $249/month 125,000,000/month 30 sec 30 days No Adds value/+EV calculations, opening and closing lines, commercial end-user display
Ultra $599/month 500,000,000/month Real-time 90 days Yes, 1 connection Adds futures

Above Ultra, the Super ($999/month), Mega ($1,499/month), and $3,499/month tiers add more concurrent WebSocket connections and longer history, and Enterprise is custom-priced for higher volume. See API pricing for the exact figures on each.

TheRundown now covers 600+ market types across 25 sportsbooks and exchanges, with sub-second delivery on all markets, prematch and in play.

Where to go next

Questions

What does TheRundown’s odds API return?
Structured JSON for each event: its markets (moneyline, spread, total, player props, and more), each market’s participants, each participant’s lines, and each line’s prices by sportsbook, with the American odds and an update timestamp.
How do moneyline, spread and total odds differ in the response?
Moneyline (market_id 1) gives each team a price and no number. Spread (market_id 2) gives each team its own signed line, such as -11.5 and +11.5. Total (market_id 3) uses Over and Under participants that share one number, such as 221.5. Every price is American odds under its sportsbook ID.
How do I authenticate requests?
Send your key in the X-TheRundown-Key header on every request to https://therundown.io/api/v2. Store it in an environment variable instead of hardcoding it in source.
How fresh are the odds I get back?
It depends on your plan: a 5-minute delay on Free, 60 seconds on Starter, 30 seconds on Pro, and real-time delivery over WebSocket on Ultra and up.
Does the free plan include player props?
No. Free covers pre-match moneyline, spread, and total lines from DraftKings, FanDuel, and BetMGM. Starter and up include every published book and market except futures, which start on Ultra. See what the free plan includes for the full breakdown.
How do I compare open sportsbook prices in Python?
Keep the event, market, period, participant and exact signed line together. A nonempty closed_at marks a closed quote; an omitted or empty field is open. Compare available quotes on that same line, keep tied prices, and skip the 0.0001 off-board sentinel. The worked example uses DraftKings and FanDuel.
Can I display the odds to my own users?
Pro and up permit commercial end-user display. Starter is for internal or personal use only. See API pricing for current terms.
How do I see every sportsbook the API covers?
Call GET /api/v2/affiliates, which lists all currently supported books and does not require a key.

Pull live odds in one request.

Get a free API key: pre-match game lines from DraftKings, FanDuel, and BetMGM, 20,000 data points a day, no credit card.