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 (Ultra+ by default). Odds updates are generally sub-second (they come straight from the sportsbooks’ own feeds); 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, and NFL Preseason is 25. 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 opening lines and GET /api/v2/events/{eventID}/closing for closing lines. For full price history over time, use GET /api/v2/events/{eventID}/markets/history or GET /api/v2/events/{eventID}/markets/{marketID}/history for chart-ready time series data. These endpoints are available after the event has started or completed. See the Events reference and Markets reference for details.
liquidity_usd is an approximate USD reading of how much money is resting in a prediction-market exchange’s order book for that price. It’s populated only for the two exchange affiliates — Kalshi (affiliate 25) and Polymarket (affiliate 26) — never for a traditional sportsbook, and is designed to extend to future exchange-style sources as they’re added. It appears on the standard price object wherever prices do — event detail, sport/date listings, best-line/odds comparisons, and WebSocket market frames (both live deltas and subscribe-time snapshots). The field itself carries no separate plan or tier requirement of its own — any key that can already reach a given surface sees it there (REST on any plan; WebSocket on the existing real-time WebSocket entitlement, Ultra and above).The two venues compute it differently:
  • Polymarket reports its own liquidity-pool figure directly, in USD.
  • Kalshi doesn’t publish a usable liquidity figure on its own market listings, so it’s derived from Kalshi’s live order book instead: the total resting cost — price × contract count, summed — across every level on both the YES and NO sides, including levels far from the current best bid/ask. It answers “how much money is resting in this book,” not “how much can trade right at today’s price.”
A missing field means “unknown,” never zero. liquidity_usd is omitted entirely — never null, never a fabricated 0 — whenever a venue doesn’t currently report a reading, including every sportsbook price and any exchange price without one yet. Don’t treat a missing field as zero liquidity.It’s a passenger value, not a live tick. The figure rides along whenever the price updates; Kalshi additionally re-reads the order book on its own background cycle roughly every 3 minutes per market, so treat it as accurate “as of the last refresh” rather than tick-by-tick. A liquidity-only change never produces a price update, a WebSocket message, or counts as line movement on its own.Why you won’t see it on every price: coverage concentrates on open, actively-quoted game markets, and Kalshi’s futures-family boards aren’t covered yet. It’s also worth knowing that every price you see has already cleared each venue’s own minimum liquidity/volume floor before it publishes at all — Polymarket requires at least 50inliquidityor50 in liquidity or 1,000 in lifetime trading volume (UFC prop markets use a higher 1,000liquidityfloorinsteadof1,000 liquidity floor instead of 50), and Kalshi requires at least 100 contracts of volume or an actively quoted two-sided book within a 0.30spread;bothvenuesalsodeclinetopublishpricesattheextremes,outsidea0.30 spread; both venues also decline to publish prices at the extremes, outside a 0.02–$0.98 band. So a published price already represents a real, minimally-liquid market even on the rare occasions liquidity_usd itself is momentarily missing.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.
No — we don’t offer free trials. The closest equivalent is weekly billing: every paid tier is available on a weekly plan, so you can run a full evaluation — including WebSocket streaming on Ultra and above — for a single week and cancel anytime. See 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 MCP Server page 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.