Skip to main content

​
General

V1 uses a flat lines model where odds are organized by sportsbook, with separate moneyline, spread, and total objects. V2 uses a market-based model where each market type (moneyline, spread, total, player props, etc.) is a separate entry with participants, lines, and prices nested inside. V2 is recommended for all new integrations — it supports player props, alternate lines, and new market types that V1 cannot represent. See the V1 to V2 Migration Guide for a detailed comparison.
A price of 0.0001 means the sportsbook has taken the line off the board — it is temporarily unavailable. This is not an error. Common causes include pending injury news, line recalculation, or approaching game time. Display it as “Off Board” or “N/A” and never use it in calculations. See Sentinel Values and Errors — The 0.0001 Sentinel Value for handling guidance.
Pass the sport_id as a path parameter when calling event endpoints: GET /api/v2/sports/{sportID}/events/{date}. For market discovery, use GET /api/v2/sports/{sportID}/markets/{date} to see which markets have active pricing for a sport on a given date. See Sport IDs for the full list of sport identifiers.
Use WebSocket when you need real-time updates for live games and your key has WebSocket access, which requires Ultra or above. Real-time odds updates are sub-second across every book. For supported live games, plays and game-stat changes stream within seconds of each other and trail the on-field action by roughly 15–20 seconds, in line with the typical broadcast delay. Use REST polling with delta endpoints for pre-match monitoring, lower-frequency updates, or as a fallback when the WebSocket disconnects. WebSocket traffic does not increment the HTTP request counter, but pushed messages are still metered as data points. Many production apps use both. See the Efficient Polling guide for recommended intervals and the WebSocket reference for connection details.
Player props are available for NFL, NBA, MLB, NHL, NCAAF, NCAAB, WNBA, UFC, and soccer leagues (IDs 10-19 and 33). CFL and tennis do not currently support player props. Player prop markets require a Starter plan or higher — Free keys do not receive them. Use GET /api/v2/sports/{sportID}/markets/{date} to check which prop markets are active for a sport on a given day. See the Market IDs reference for prop market IDs like Player Points (29), Player Rebounds (35), and Player Assists (39).

​
Data & IDs

Soccer leagues (IDs 10-19 and 33) do not use the standard rotation number system that US sportsbooks use for football, basketball, and other sports. Instead, soccer event IDs are generated from the participating team IDs and match date. This means you cannot look up a soccer event by rotation number — use the events-by-date endpoint or search by team ID instead. See Sports & Coverage for more details.
Preseason, playoff, and special-event games have their own sport IDs separate from the parent league’s regular season. For example, NBA Preseason is sport ID 23, NBA Playoffs is 24, NFL Preseason is 25, NHL Preseason is 27, and MLB Playoffs is 31. This lets you filter or subscribe to specific parts of a season independently. Season-specific sports share the same data model and endpoints as their parent sport. See the full list of season-specific IDs.
Use GET /api/v2/sports/{sportID}/futures — futures (outrights) are served as competition events with their own stable event_id, separate from the dated game endpoints. Championship winner boards are live for NFL, MLB, NCAAF, NHL, NBA, NCAAB, WNBA, and EPL, plus per-tournament PGA Tour golf (sport ID 40) and Formula 1 season championships (sport ID 41). Futures are in early access and require an Ultra plan or higher on API keys. See the Futures guide for the data model, window semantics, and the delta polling recipe.
Use GET /api/v2/events/{eventID}/openers for the first recorded prices and GET /api/v2/events/{eventID}/closing for the latest recorded prices at or before the event’s scheduled start. Openers and history can contain data before, during, or after an event when prices were recorded. A pre-start closing response is provisional and may change until the scheduled start.For full price history, use GET /api/v2/events/{eventID}/markets/history, which returns history rows newest first, or GET /api/v2/events/{eventID}/markets/{marketID}/history, which returns chart-ready series. Pass participant_id to isolate a selection. History access is subject to the plan’s history window.See the Historical Odds guide, opening prices reference, closing prices reference, Events reference, and Markets reference for details.
liquidity_usd is a USD reading on supported V2 price objects. The meaning depends on the affiliate:
  • Kalshi (affiliate 25) and Polymarket (affiliate 26): approximate resting order-book depth.
  • Pinnacle (affiliate 3): the book’s max stake for that price.
It appears on supported price surfaces, including event detail, sport/date listings, comparisons, and WebSocket market frames. Access follows the plan requirements of the surface: WebSocket access requires Ultra or above.A missing field means the value is unavailable, not zero. The field is omitted when a current reading is not available. It travels with price updates and does not by itself indicate price movement.See the Price object reference for the field’s exact shape.

​
Billing & Plans

Upgrades take effect immediately once payment succeeds. The prorated charge for the remainder of the billing period is invoiced at upgrade time — if the payment fails, the upgrade is not applied and your current plan stays active. As soon as the upgrade completes, your API keys reflect the new tier’s data points, rate limits, and feature access with no waiting period.
You can schedule a downgrade from your dashboard at any time. Downgrades take effect at the end of the current billing period — you keep your current tier’s allowance and features until then, and nothing extra is charged when you schedule it. You can cancel a scheduled downgrade any time before the period ends.
Yes. Every paid API tier is available on a weekly billing cadence at a premium over the monthly price — useful for covering a single tournament or a few weeks of a season without a month-long commitment. Weekly plans include a proportional weekly share of the tier’s monthly data-point allowance (monthly × 12 ÷ 52), metered over the 7-day billing window, with overage at the same per-data-point rates. The X-Datapoints-Period header reads weekly on these plans. See Weekly Billing.
We do not offer a free trial of paid API plans. New Free accounts created on or after 2026-09-07T18:00:00Z receive a no-card, seven-day evaluation from account creation with current-season completed-game stats and current-season aggregates. After it ends, the fixed sample and stats catalog remain free; ongoing access to current-season completed-game stats and season aggregates starts on Starter. Every paid tier is also available on weekly billing for short-term use. See Stats Access and Weekly Billing.
If your account has an outstanding balance (unpaid overage or an open invoice), cancellation is blocked until the balance is settled. Similarly, if a subscription payment has failed and the account is payment-suspended, new API keys cannot be created and plan upgrades are blocked until the payment issue is resolved from your dashboard.

​
Integration

TheRundown enforces two different limits per API key: data-point usage and requests per second. Metered responses include headers like X-Datapoints, X-Datapoints-Used, X-Datapoints-Remaining, X-Tier, and X-Rate-Limit. To stay efficient: use delta endpoints instead of repeated full snapshots, filter by market_ids and affiliate_ids, cache reference data, and use WebSocket on real-time tiers when you need live updates. When you get a 429, read Retry-After and the billing headers to determine whether you hit a short burst throttle or a usage cap. See Rate Limits and the Efficient Polling guide.
Yes. WebSocket traffic does not increment the HTTP request counter, but snapshot payloads and pushed updates are still metered as data points. A game_stats frame costs one stats data point per changed team or player stat row; a zero-row completion marker or invalidation fallback costs one. Keep subscriptions narrow by filtering to the sports, markets, events, and sportsbooks you actually need.
Delta endpoints use cursor-based pagination, and there are two of them with different, non-interchangeable cursors:
  • /api/v2/markets/delta (price changes) takes an integer cursor. Bootstrap it from the integer meta.delta_last_id in a /api/v2/sports/{id}/events/{date} response, then follow the integer meta.delta_last_id returned by each markets-delta response. This is the endpoint for odds polling.
  • /api/v2/delta (full event-object changes — status, scores, the whole event) takes an ordered UUID cursor (e.g. 11f1-23b3-f4d42784-8057-a3a997572248) that is only returned by /api/v2/delta’s own responses. The events snapshot does not provide it, and passing the integer cursor here returns a 400.
Don’t bootstrap with last_id=0 — cursors that fall too far behind the current head are rejected; always seed from a fresh events snapshot. Each delta entry contains the full updated object, so replace (don’t merge) in your local cache. See the Efficient Polling guide for the complete flow.
Yes. TheRundown provides a Model Context Protocol (MCP) server that lets AI assistants like Claude, Cursor, VS Code Copilot, and others search the API documentation directly. The MCP server is documentation-only: it helps your assistant find endpoints, parameters, market IDs, and examples, but live sports data still comes from your own API key calling the real API. See the Documentation MCP guide for setup instructions and example prompts.
TheRundown provides official SDKs for Python, JavaScript, and Go. These wrap the REST API with typed methods for events, markets, teams, players, and stats. If your language isn’t covered, the API is a standard REST interface that works with any HTTP client.