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

  <Accordion title="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](/api-reference/v2/events) and [Markets reference](/api-reference/v2/markets) for details.
  </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. 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](/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 [MCP Server page](/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>