1. Get your API key
Sign up at therundown.io/api to get your API key, then store it in the privateTHERUNDOWN_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.
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.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 anevents 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.
4. Choose your update path
For a plan with explicitly confirmed zero data delay, bootstrap with a narrow event snapshot and reuse its validmeta.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 responsesBuilding 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