Make your first sports odds API request

Step 1

Get your API key

The Free tier includes 20,000 data points per UTC day, up to 200,000 per UTC calendar month, with no credit card. Your free API key is available in the account dashboard after signup. Paid plans meter a monthly allowance (weekly-billed plans get a proportional weekly share over each 7-day window); every response’s X-Datapoints-Used/-Remaining/-Limit/-Period headers show your live quota. Monthly and annual self-serve plans are hard-capped by default; optional per-point overage requires explicit opt-in. New weekly subscriptions start with automatic metered overage. Explicitly enabling overage on a monthly or annual plan without a saved dollar limit creates an initial cap equal to one subscription-period price. A weekly plan without a saved limit uses a 3× weekly-price fallback. Either cap can be edited in Spend Controls.

1. Sign up

   Create an account with email + password. No credit card.

2. Copy your key

   Your free API key is in the account dashboard. Set it in the private THERUNDOWN_API_KEY environment variable, then send it as X-TheRundown-Key on every request.

3. Make your first call

   Use any HTTP client. JSON response, REST semantics, sortable by event, sportsbook, or market.

Step 2

Make your first request

Choose a current sport or category, then copy its bounded request in any language. MLB is the default illustrative sport. Check the sports reference and /api/v2/sports before relying on a result. For odds, each returned participant/outcome × line/value × sportsbook price is one point. V2 event snapshots also add event, score, and live-state rows. X-Datapoints is authoritative for the billed total on billed responses. X-Datapoints-Breakdown is optional, and is not currently emitted by /api/v2/markets/delta.

DATE=$(date -u +%F)
if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
  echo "Set THERUNDOWN_API_KEY before running this example." >&2
  exit 1
fi
URL="https://therundown.io/api/v2/sports/3/events/${DATE}?market_ids=1,2,3,41,42,43&affiliate_ids=3,19,23&main_line=true&hide_closed=true"

curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
  -D response-headers.txt -o response.json "$URL" \
  -H "X-TheRundown-Key: $THERUNDOWN_API_KEY"
curl_exit_status=$?
if [ "$curl_exit_status" -ne 0 ]; then exit "$curl_exit_status"; fi
awk 'tolower($1) == "x-datapoints:" { print "Billed data points: " $2 }' response-headers.txt
jq '{events: ((.events // []) | length)}' response.json

Step 3

Choose a polling pattern

Free, delayed, or unknown entitlement: repeat the same filtered MLB snapshot for sport 3 with the literal market IDs market_ids=1,2,3,41,42,43 (including live IDs 41, 42, and 43) and affiliate_ids=3,19,23 at the cadence your use case needs. Every successful snapshot bills its returned rows.

Use market deltas only with a known zero-delay entitlement: the bootstrap response must explicitly return X-Data-Delay-Seconds: 0. Read a valid positive integer (as a number or numeric string) from the response body's meta.delta_last_id. Do not use deltas when the delay header is missing, invalid, or positive, and never treat a missing cursor or delay as zero.

For an eligible zero-delay account, poll /api/v2/markets/delta?last_id=CURSOR&sport_id=3&market_ids=1,2,3,41,42,43&affiliate_ids=3,19,23 with that positive body cursor. Process bounded pages while meta.has_more is true, save each next positive cursor, and rebootstrap once after an invalid cursor or 400 response. See efficient polling guidance for pagination details.