Skip to main content

1. Get your API key

Sign up at therundown.io/api to get your API key, then store it in the private THERUNDOWN_API_KEY environment variable of your server-side application.

2. Make your first request

Some reference endpoints are public, but authenticating from the start lets you see the same headers and behavior your production integration will use.
You’ll receive a list of available sports with their IDs. A shortened example:

3. Get today’s MLB odds

These examples use the current UTC date. The offset parameter shifts the date boundary so a “day” aligns with the timezone you care about instead of midnight UTC. When you use an offset, choose the date for that same market-day boundary. A date with no events can simply be outside the season or schedule; check available dates before treating it as a coverage gap.
This MLB example uses the explicit full-game core scope. For soccer, NHL regulation-time, tennis, futures, and every current sport ID, see the recommended core market scopes. In production, market_ids, affiliate_ids, and main_line=true are your biggest levers for controlling payload size and data-point usage.
Fetch GET /api/v2/affiliates instead of hard-coding the source roster. Current IDs include BookMaker (7), BetCRIS (9), Circa Sports (32), Bet105 (33), and Heritage Sports (34). Availability varies by source, sport, and market; see Sportsbook IDs for the complete current mapping.

Opening and closing snapshots

Historical snapshots require a plan with historical access. Opening snapshots return the earliest recorded price for each available line and sportsbook. Closing snapshots return the latest recorded price at or before scheduled event start; a closing snapshot queried before start is provisional. Both are returned in an events array, even for one event. Use https://therundown.io with the full /api/v2/events/{eventID}/closing path. If your client already uses https://therundown.io/api/v2 as its base URL, append only /events/{eventID}/closing. The final URL contains /api exactly once.
Replace the event ID with one within your plan’s history window. For all parameters and response shapes, see the event opening reference, event closing reference, and historical odds guide.

4. Choose your update path

For a plan with explicitly confirmed zero data delay, bootstrap with a narrow event snapshot and reuse its valid meta.delta_last_id cursor for market-delta polling. Do not start with last_id=0; see Efficient Polling for the bounded bootstrap and recovery flow. Delayed plans use repeated narrow snapshots instead. If your server-side key has X-Websocket-Access: true, you can connect to the WebSocket feed for real-time updates. WebSocket access requires an Ultra plan or higher. Run this in Node.js 22+ ESM (.mjs or "type": "module") and install ws with npm install ws on your server; browser WebSocket clients cannot set this authentication header and should connect to your authenticated backend relay instead.
Node.js 22+ (ESM)
If your key does not have WebSocket access, use market delta polling instead.

Next steps

Authentication

Learn about all auth methods

Rate Limits

Understand data points and 429 responses

Building an Odds Screen

Step-by-step guide

Efficient Polling

Delta, caching, and cost control

Market IDs Reference

All market types and their IDs

WebSocket Streaming

Real-time data guide