> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therundown.io/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

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

## General

<AccordionGroup>
  <Accordion title="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](/guides/v1-to-v2-migration) for a detailed comparison.
  </Accordion>

  <Accordion title="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](/reference/sentinel-values) and [Errors — The 0.0001 Sentinel Value](/errors#the-0-0001-sentinel-value) for handling guidance.
  </Accordion>

  <Accordion title="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](/reference/sports) for the full list of sport identifiers.
  </Accordion>

  <Accordion title="Should I use WebSocket or REST polling?">
    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](/guides/efficient-polling) for recommended intervals and the [WebSocket reference](/api-reference/v2/websocket) for connection details.
  </Accordion>

  <Accordion title="Which sports support player props?">
    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](/reference/markets) for prop market IDs like Player Points (29), Player Rebounds (35), and Player Assists (39).
  </Accordion>
</AccordionGroup>

## Data & IDs

<AccordionGroup>
  <Accordion title="How are soccer event IDs generated?">
    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](/reference/sports) for more details.
  </Accordion>

  <Accordion title="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`, 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](/reference/sports#season-specific-sports).
  </Accordion>

  <Accordion title="How do I get futures / championship odds?">
    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](/guides/futures) for the data model, window semantics, and the delta polling recipe.
  </Accordion>

  <Accordion title="How do I get historical or closing lines?">
    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](/guides/historical-odds), [opening prices reference](/api-reference/generated/v2-events/get-opening-prices-for-an-event), [closing prices reference](/api-reference/generated/v2-events/get-closing-prices-for-an-event), [Events reference](/api-reference/v2/events), and [Markets reference](/api-reference/v2/markets) for details.
  </Accordion>

  <Accordion title="What is `liquidity_usd` on a price object?">
    `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](/reference/data-model#price-object) for the field's exact shape.
  </Accordion>
</AccordionGroup>

## Billing & Plans

<AccordionGroup>
  <Accordion title="What happens when I upgrade my plan?">
    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.
  </Accordion>

  <Accordion title="How do I downgrade my plan?">
    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.
  </Accordion>

  <Accordion title="Can I pay weekly instead of monthly?">
    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](/rate-limits#weekly-billing).
  </Accordion>

  <Accordion title="Is there a free trial?">
    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](/guides/stats-access) and [Weekly Billing](/rate-limits#weekly-billing).
  </Accordion>

  <Accordion title="Why can't I cancel or create new API keys?">
    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.
  </Accordion>
</AccordionGroup>

## Integration

<AccordionGroup>
  <Accordion title="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](/rate-limits) and the [Efficient Polling guide](/guides/efficient-polling).
  </Accordion>

  <Accordion title="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. 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.
  </Accordion>

  <Accordion title="How does the delta cursor work?">
    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](/guides/efficient-polling#delta-endpoint-bootstrap-flow) for the complete flow.
  </Accordion>

  <Accordion title="Can I use an MCP server to query the docs from my editor?">
    Yes. TheRundown provides a [Model Context Protocol (MCP) server](/documentation-mcp) 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](/documentation-mcp) for setup instructions and example prompts.
  </Accordion>

  <Accordion title="Where can I find SDKs or client libraries?">
    TheRundown provides official SDKs for [Python](/sdks/python), [JavaScript](/sdks/javascript), and [Go](/sdks/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.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.