FAQ

Frequently asked questions about TheRundown API — data model, common issues, and integration tips.

General

What is the difference between V1 and V2?

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.

What does the 0.0001 sentinel value mean?

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.

How do I filter events or markets by sport?

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.

Should I use WebSocket or REST polling?

Use WebSocket when you need sub-second updates for live games and your key has WebSocket access (Ultra+ by default). 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.

Which sports support player props?

Player props are available for NFL, NBA, MLB, NHL, NCAAF, NCAAB, WNBA, UFC, and soccer leagues (IDs 10–19). CFL does not currently support player props. 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

How are soccer event IDs generated?

Soccer leagues (IDs 10–19) 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.

What are season-specific sport IDs?

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.

How do I get historical or closing lines?

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.

Integration

How do rate limits work and how do I stay under them?

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.

Do WebSocket messages count toward usage?

Yes. WebSocket traffic does not increment the HTTP request counter, but snapshot payloads and pushed updates are still metered as data points. Keep subscriptions narrow by filtering to the sports, markets, events, and sportsbooks you actually need.

How does the delta cursor work?

Delta endpoints use cursor-based pagination. On your first call, pass last_id=0 (market delta) or a zeroed UUID (event delta). The response includes a delta_last_id — save this value and pass it as last_id on your next call to receive only changes since that point. Each delta entry contains the full updated object, so replace (don’t merge) in your local cache. If your cursor goes stale, re-fetch a full snapshot and start over. See the Efficient Polling guide for the complete bootstrap flow.

Can I use an MCP server to query the docs from my editor?

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.

Where can I find SDKs or client libraries?

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.