Odds API: from a key to your first measured response

Authenticate and discover reference IDs

Create a Free key and store it as THERUNDOWN_API_KEY on your server or local development environment. Send X-TheRundown-Key on HTTPS requests. Do not embed a private key in a public browser bundle. Authentication and feature access apply even when a reference route costs no data points.

The base for Product V2 requests is https://therundown.io/api/v2. Sports, affiliates and markets are separate ID namespaces. Discover them through authenticated catalog endpoints, then use canonical event_id values returned by events. event_uuid is retained for compatibility and must not replace event_id in V2 paths.

• Authentication
• Canonical identifiers

Make a narrow first request with curl

This sample discovers the catalog, waits between requests for Free’s one-request-per-second rate limit, then requests today’s UTC regular-season NFL moneyline from DraftKings. A date without NFL games can legitimately return an empty array. Choose an active catalog sport and date for your evaluation.

Use main_line=true to keep primary lines and hide_closed=true to omit closed prices. Inspect response-headers.txt for X-Datapoints and the effective plan-delay headers. The returned payload is still subject to your key’s coverage and delayed access.

# Set THERUNDOWN_API_KEY in your environment first.
# Catalog requests require authentication but cost no data points.
curl --fail-with-body --silent --show-error \
  -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
  "https://therundown.io/api/v2/sports"

# Free allows 1 request/second. Pace this second request.
sleep 1.1
DAY=$(date -u +%F)
curl --fail-with-body --silent --show-error --dump-header response-headers.txt \
  -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
  "https://therundown.io/api/v2/sports/2/events/$DAY?market_ids=1&affiliate_ids=19&main_line=true&hide_closed=true"
# Read X-Datapoints in response-headers.txt to measure billed usage.

Read the nested JSON without losing identity

The event response has an events array. Each event has markets; a market has participants; a participant has lines; each line has a prices map keyed by affiliate ID. A price includes American odds for sportsbook sources and may include source metadata. Do not assume an array position selects a particular market or source.

Join on IDs rather than names. A team participant ID matches a normalized team resource; a player participant points to a player resource; a result participant represents an outcome such as Over or Under. Preserve period_id, signed line value and line ID in your storage key.

Handle HTTP 401 authentication errors, 403 entitlement errors and 429 limits in your client. Error responses should not be silently parsed as empty successful slates. Apply bounded retries appropriate to the error and avoid rapid retry loops on a one-request-per-second key.

• Full JSON model

Measure rows before expanding the request

A request is not one data point. Returned price rows are metered alongside event/score categories where present. One two-sided moneyline game from one book typically has two price rows plus an event and a score point: four points without live_game_state. Missing prices or score fields change the result; live_game_state adds another score point.

Repeated successful snapshots bill returned rows again, even if prices did not change. Choose a cadence suited to the plan delay. Ultra and higher zero-delay plans can use the documented delta or WebSocket patterns; do not seed a zero-delay delta cursor from a delayed snapshot.

Paid plans combine fixed fees and included volume. Narrowing affiliate_ids and market_ids avoids metering unused prices but does not reduce the base subscription fee. Keep response usage evidence alongside your workload estimate.

• Billing, rate limits and delay
• Efficient polling and delta rules

Odds API pricing and plan delays

Published USD monthly plans start at Free, Starter $49, Pro $149 and Ultra $399. Select the feature set first, then size your included data-point volume. Free and Starter are for internal or personal use; commercial end-user display begins on Pro. Real-time odds and WebSocket begin on Ultra. Paid plans have a fixed subscription fee with included data-point volume. Choose the sports, books and markets your application needs: unrequested price rows do not consume that volume, but using fewer points does not reduce the base fee. Measure each request with X-Datapoints; requests, event objects, credits and data points are different billing units.

Annual billing has different monthly equivalents. Monthly and annual plans stop at included data points by default; optional overage and weekly billing have separate terms. Super, Mega and Max add published volume and connection capacity; Enterprise is scoped by contract. Confirm effective API and stats access in response headers.

Odds API FAQ

How do I get a free odds API key?

Create a TheRundown account and activate Free without a credit card. Store the key securely and send it through X-TheRundown-Key on Product API requests. Free access has coverage, delay, rate and volume limits.

What is the odds API base URL?

Product V2 requests use https://therundown.io/api/v2. Event snapshots are under /sports/{sportID}/events/{date} or /events/{eventID}; discover reference IDs from the authenticated catalogs.

Is one request equal to one data point?

No. Returned price rows plus event/score/live-state categories determine usage. Read X-Datapoints on a successful response. Repeated snapshots can bill the same unchanged rows again.

Can I replace another provider’s base URL with this one?

No. Authentication, IDs, response nesting, closure semantics and billing units differ. Map the data model and validate one sport, market and source before changing production traffic.

Build and compare

Choose the API scope that matches your application. Each guide below covers a different integration need.

Product and documentation sources checked October 13, 2026. Source, sport, event and market availability varies; catalog entries do not guarantee a priced line or a populated statistic.