# TheRundown API

- [TheRundown Sports API](https://docs.therundown.io/introduction.md): Sports betting data from sportsbooks and exchanges — real-time odds, futures, play-by-play, scores, stats, and schedules
- [Quickstart](https://docs.therundown.io/quickstart.md): Get your first API response, understand your usage headers, and choose the right update path.
- [Authentication](https://docs.therundown.io/authentication.md): Learn how to authenticate your requests to TheRundown API using API keys.
- [Documentation MCP](https://docs.therundown.io/documentation-mcp.md): Connect TheRundown API docs to Codex, Claude, Cursor, and other AI assistants.
- [Data MCP](https://docs.therundown.io/data-mcp.md): Connect Codex, Claude, Cursor, or VS Code to six read-only sports data tools through TheRundown's hosted Streamable HTTP endpoint or the local stdio MCP server, using your own API key.
- [AI discovery evaluation](https://docs.therundown.io/ai-evaluation.md): A public prompt corpus for evaluating how AI systems discover and describe TheRundown from official sources.
- [Data MCP design](https://docs.therundown.io/data-mcp-design.md): Architecture, data contracts, limits, and release criteria for the local TheRundown data MCP scaffold.
- [Rate Limits](https://docs.therundown.io/rate-limits.md): Understand data-point costs, plan history windows, per-second throttles, usage headers, and error responses.
- [Licensing & Attribution](https://docs.therundown.io/licensing-and-attribution.md): What your plan lets you do with TheRundown data, how to attribute it, and when you need a Supplemental Agreement.
- [Errors](https://docs.therundown.io/errors.md): HTTP status codes, error response formats, and troubleshooting guidance for TheRundown API.
- [FAQ](https://docs.therundown.io/faq.md): Frequently asked questions about TheRundown API — data model, common issues, and integration tips.
- [Changelog](https://docs.therundown.io/changelog.md): Recent updates, new features, and improvements to TheRundown API.
- [Data Model](https://docs.therundown.io/reference/data-model.md): How events, markets, participants, lines, and prices relate to each other in the V2 API.
- [Sports & Coverage](https://docs.therundown.io/reference/sports.md)
- [Sportsbook / Affiliate IDs](https://docs.therundown.io/reference/sportsbooks.md)
- [Market IDs](https://docs.therundown.io/reference/markets.md)
- [Period IDs](https://docs.therundown.io/reference/periods.md)
- [Live Game State](https://docs.therundown.io/reference/live-game-state.md): Period, clock, and sport-specific in-game situation, plus the play-by-play timeline shape.
- [Event Status Codes](https://docs.therundown.io/reference/event-statuses.md)
- [Sentinel Values](https://docs.therundown.io/reference/sentinel-values.md)
- [List all sports](https://docs.therundown.io/api-reference/generated/v2-sports/list-all-sports.md): Returns all available sports with their IDs. No authentication required.
- [Get available dates for multiple sports](https://docs.therundown.io/api-reference/generated/v2-sports/get-available-dates-for-multiple-sports.md): Returns dates with events for the specified sport IDs.
- [Get events across sports for a date](https://docs.therundown.io/api-reference/generated/v2-sports/get-events-across-sports-for-a-date.md): Returns schedule listing dates grouped by sport (`sport_id` → date strings) for the given date.
- [Get available markets by date](https://docs.therundown.io/api-reference/generated/v2-sports/get-available-markets-by-date.md): Returns available market definitions for each sport on the given date.
- [Get teams for a sport](https://docs.therundown.io/api-reference/generated/v2-sports/get-teams-for-a-sport.md)
- [Get available dates for a sport](https://docs.therundown.io/api-reference/generated/v2-sports/get-available-dates-for-a-sport.md)
- [Get divisions for a sport](https://docs.therundown.io/api-reference/generated/v2-sports/get-divisions-for-a-sport.md)
- [Get conferences for a sport](https://docs.therundown.io/api-reference/generated/v2-sports/get-conferences-for-a-sport.md)
- [Get events with markets for a sport and date](https://docs.therundown.io/api-reference/generated/v2-events/get-events-with-markets-for-a-sport-and-date.md): Returns events with full market/odds data for the specified sport and date. This is the primary endpoint for building odds screens.
- [Get opening lines for a sport and date](https://docs.therundown.io/api-reference/generated/v2-events/get-opening-lines-for-a-sport-and-date.md): Returns events with the earliest recorded price for each available line at each sportsbook. Opening snapshots are available whenever a price has been recorded, including before, during, or after an event.
- [Get closing lines for a sport and date](https://docs.therundown.io/api-reference/generated/v2-events/get-closing-lines-for-a-sport-and-date.md): Returns events with the latest recorded price for each available line and sportsbook at or before each event's scheduled start time. Before an event starts, the snapshot is provisional. Period markets use the event start time as their closing cutoff.
- [Get a single event with markets](https://docs.therundown.io/api-reference/generated/v2-events/get-a-single-event-with-markets.md): `main_line=true` also excludes closed prices while selecting main lines.
- [Get opening prices for an event](https://docs.therundown.io/api-reference/generated/v2-events/get-opening-prices-for-an-event.md): Returns the earliest recorded price for each available line at each sportsbook. Opening snapshots are available whenever a price has been recorded, including before, during, or after an event. The response always uses an `events` array, even for one event ID.
- [Get closing prices for an event](https://docs.therundown.io/api-reference/generated/v2-events/get-closing-prices-for-an-event.md): Returns the latest recorded price for each available line and sportsbook at or before the event's scheduled start time. Before the event starts, the snapshot is provisional. Period markets use the event start time as their closing cutoff. The response always uses an `events` array, even for one even…
- [Get best available line for an event](https://docs.therundown.io/api-reference/generated/v2-events/get-best-available-line-for-an-event.md): Returns the best moneyline, spread, and total across all sportsbooks.
- [Get play-by-play for an event](https://docs.therundown.io/api-reference/generated/v2-events/get-play-by-play-for-an-event.md): Returns the play-by-play timeline for a live or completed event — one entry per play with description, period, game clock, running score, and (as attribution rolls out) the players involved. Live game state and play-by-play require an **Ultra plan or higher**; keys on lower tiers receive a `403`. Th…
- [Get event changes since a delta ID](https://docs.therundown.io/api-reference/generated/v2-events/get-event-changes-since-a-delta-id.md): Returns raw JSON delta payloads for events that changed since `last_id`. Each delta entry is a raw JSON string containing the full event update — the `data` field is a serialized JSON string, not a parsed object.
- [Get available markets for a sport and date](https://docs.therundown.io/api-reference/generated/v2-markets/get-available-markets-for-a-sport-and-date.md)
- [Get available markets for an event](https://docs.therundown.io/api-reference/generated/v2-markets/get-available-markets-for-an-event.md): Returns the list of market definitions available for this event (not prices — use the event endpoint with market_ids for prices).
- [Get market price history for an event](https://docs.therundown.io/api-reference/generated/v2-markets/get-market-price-history-for-an-event.md): Returns recorded price changes for the requested markets and sportsbooks, subject to your plan's historical-data access. Data can be available before, during, or after an event as prices are recorded. Each response is bounded by the requested limit.
- [Get opening prices for an event's markets](https://docs.therundown.io/api-reference/generated/v2-markets/get-opening-prices-for-an-events-markets.md)
- [Get line price chart data for a specific market](https://docs.therundown.io/api-reference/generated/v2-markets/get-line-price-chart-data-for-a-specific-market.md): Returns time-series price data suitable for charting line movement. To chart one participant, first discover its public `participant_id` with `GET /api/v2/markets/participants` for the same event and market, then pass that value here. For totals (market `3`), discover the `TYPE_RESULT` Over and Unde…
- [List all market definitions](https://docs.therundown.io/api-reference/generated/v2-markets/list-all-market-definitions.md): Returns all canonical market definitions with IDs, names, period info, and whether the line value represents a participant.
- [Get market price changes since a given ID](https://docs.therundown.io/api-reference/generated/v2-markets/get-market-price-changes-since-a-given-id.md): Returns market line price changes (new, updated, closed) since the specified `last_id`. Use for efficient polling.
- [Get price history for specific market line prices](https://docs.therundown.io/api-reference/generated/v2-markets/get-price-history-for-specific-market-line-prices.md)
- [Get market participants](https://docs.therundown.io/api-reference/generated/v2-markets/get-market-participants.md): Lists teams, players, or result sides for the requested event and markets. Use `participant_id` from this response, rather than `id`, to filter a participant-specific chart. Market `3` totals use `TYPE_RESULT` Over and Under participants, while markets `1` and `2` use `TYPE_TEAM` participants. For e…
- [Get futures for a sport](https://docs.therundown.io/api-reference/generated/v2-futures/get-futures-for-a-sport.md): Returns futures/outright **competition events** (e.g. tournament winner) for a sport, with future-class markets in the standard V2 market → participants → lines → prices shape and per-market settlement state. Competition events are excluded from the dated game endpoints and served only here. **Early…
- [Get one futures competition, with progress and leaders](https://docs.therundown.io/api-reference/generated/v2-futures/get-one-futures-competition.md): Returns **one** futures/outright competition event — the same envelope and event object shape as `GET /api/v2/sports/{sportID}/futures` (`meta.delta_last_id`, `events` with a single event carrying `event_id`, `sport_id`, `event_date`, `settle_by`, `event_status`, `settlement`, `schedule`, `markets`)…
- [Get a team by ID](https://docs.therundown.io/api-reference/generated/v2-teams/get-a-team-by-id.md)
- [Get players for a team](https://docs.therundown.io/api-reference/generated/v2-teams/get-players-for-a-team.md)
- [Get season stats for a team](https://docs.therundown.io/api-reference/generated/v2-teams/get-season-stats-for-a-team.md)
- [Get player season stats for a team](https://docs.therundown.io/api-reference/generated/v2-teams/get-player-season-stats-for-a-team.md)
- [Get a player by ID](https://docs.therundown.io/api-reference/generated/v2-players/get-a-player-by-id.md)
- [Stats](https://docs.therundown.io/api-reference/v2/stats.md): Stat definitions, REST box scores, and live team/player game-stat deltas
- [Get a fixed complete-game stats sample](https://docs.therundown.io/api-reference/generated/v2-stats/get-fixed-complete-game-stats-sample.md): Returns a static, marked sample game box for schema and parsing tests. It requires an API key but consumes zero data points. It is not a production-data entitlement and must not be polled.
- [Get team game stats for an event](https://docs.therundown.io/api-reference/generated/v2-stats/get-team-game-stats-for-an-event.md)
- [Get player game stats for an event](https://docs.therundown.io/api-reference/generated/v2-stats/get-player-game-stats-for-an-event.md)
- [List all stat definitions](https://docs.therundown.io/api-reference/generated/v2-stats/list-all-stat-definitions.md)
- [List all sportsbooks/affiliates](https://docs.therundown.io/api-reference/generated/v2-reference/list-all-sportsbooksaffiliates.md): Returns currently published sportsbooks with IDs, names, URLs, and an integration `status` (`healthy`, `unhealthy`, or `beta`). Availability can vary by sport and market. No authentication required.
- [List all sportsbooks (alias for /affiliates)](https://docs.therundown.io/api-reference/generated/v2-reference/list-all-sportsbooks-alias-for-affiliates.md)
- [List season types per sport](https://docs.therundown.io/api-reference/generated/v2-reference/list-season-types-per-sport.md)
- [WebSocket](https://docs.therundown.io/api-reference/v2/websocket.md): Real-time streaming of odds, scores, plays, and game stats via WebSocket
- [Markets WebSocket — stream real-time market price updates](https://docs.therundown.io/api-reference/generated/v2-websocket/markets-websocket-—-stream-real-time-market-price-updates.md): Establishes a WebSocket connection for streaming V2 market price changes in real-time.
- [Multiplexed WebSocket — subscribe to markets, scores, plays, stats, and live channels](https://docs.therundown.io/api-reference/generated/v2-websocket/multiplexed-websocket-—-subscribe-to-markets-scores-plays-and-live-channels.md): Establishes a single WebSocket connection carrying multiple logical channels. Instead of query-parameter filters, send JSON subscribe messages after connecting.
- [Get a single event with lines](https://docs.therundown.io/api-reference/generated/v1-events/get-a-single-event-with-lines.md)
- [Get event by line ID](https://docs.therundown.io/api-reference/generated/v1-events/get-event-by-line-id.md)
- [Get events with lines for a sport and date](https://docs.therundown.io/api-reference/generated/v1-events/get-events-with-lines-for-a-sport-and-date.md)
- [Get opening lines for a sport and date](https://docs.therundown.io/api-reference/generated/v1-events/get-opening-lines-for-a-sport-and-date.md)
- [Get closing lines for a sport and date](https://docs.therundown.io/api-reference/generated/v1-events/get-closing-lines-for-a-sport-and-date.md)
- [Get best lines for multiple events](https://docs.therundown.io/api-reference/generated/v1-lines/get-best-lines-for-multiple-events.md)
- [Get moneylines for an event](https://docs.therundown.io/api-reference/generated/v1-lines/get-moneylines-for-an-event.md)
- [Get spreads for an event](https://docs.therundown.io/api-reference/generated/v1-lines/get-spreads-for-an-event.md)
- [Get totals (over/under) for an event](https://docs.therundown.io/api-reference/generated/v1-lines/get-totals-overunder-for-an-event.md)
- [Get team totals for an event](https://docs.therundown.io/api-reference/generated/v1-lines/get-team-totals-for-an-event.md)
- [List all sports](https://docs.therundown.io/api-reference/generated/v1-sports/list-all-sports.md)
- [Get teams for a sport](https://docs.therundown.io/api-reference/generated/v1-sports/get-teams-for-a-sport.md)
- [Get divisions for a sport](https://docs.therundown.io/api-reference/generated/v1-sports/get-divisions-for-a-sport.md)
- [Get conferences for a sport](https://docs.therundown.io/api-reference/generated/v1-sports/get-conferences-for-a-sport.md)
- [Get available dates for a sport](https://docs.therundown.io/api-reference/generated/v1-sports/get-available-dates-for-a-sport.md)
- [Get event schedule for a sport](https://docs.therundown.io/api-reference/generated/v1-sports/get-event-schedule-for-a-sport.md)
- [Get event deltas (V1 format)](https://docs.therundown.io/api-reference/generated/v1-delta/get-event-deltas-v1-format.md)
- [Get event deltas (V2 format via V1 path)](https://docs.therundown.io/api-reference/generated/v1-delta/get-event-deltas-v2-format-via-v1-path.md)
- [List all sportsbooks/affiliates](https://docs.therundown.io/api-reference/generated/v1-reference/list-all-sportsbooksaffiliates.md)
- [List all sportsbooks (alias)](https://docs.therundown.io/api-reference/generated/v1-reference/list-all-sportsbooks-alias.md)
- [List season types per sport](https://docs.therundown.io/api-reference/generated/v1-reference/list-season-types-per-sport.md)
- [V1 WebSocket — stream real-time event and market updates](https://docs.therundown.io/api-reference/generated/v1-websocket/v1-websocket-—-stream-real-time-event-and-market-updates.md): Establishes a WebSocket connection for streaming V1 event updates and V2 market price deltas.
- [Getting Live Odds](https://docs.therundown.io/guides/getting-live-odds.md): Fetch real-time moneylines, spreads, and totals from multiple sportsbooks using the V2 events endpoint.
- [Building an Odds Screen](https://docs.therundown.io/guides/building-odds-screen.md): Step-by-step guide to building a real-time odds screen with moneyline, spread, and total columns using TheRundown API and WebSocket.
- [Historical Odds & Line Movement](https://docs.therundown.io/guides/historical-odds.md): Retrieve opening lines, closing lines, and full price history to build line movement charts and analyze odds changes over time.
- [Scores and Results](https://docs.therundown.io/guides/scores-and-results.md): Read final and per-period scores, derive half scores defensively, and retrieve completed results within your plan's history and data-point limits.
- [Player Props](https://docs.therundown.io/guides/player-props.md): Fetch player prop odds including points, rebounds, assists, three-pointers, and combo markets using the V2 markets system.
- [Stats Access](https://docs.therundown.io/guides/stats-access.md): Understand the new-account stats policy, legacy access, fixed samples, coverage limits, and upgrades.
- [Futures & Outrights](https://docs.therundown.io/guides/futures.md): List championship and tournament-winner boards, page through competitions, and keep futures prices fresh with the markets delta feed.
- [WebSocket Streaming](https://docs.therundown.io/guides/websocket-streaming.md): Connect to TheRundown WebSocket feeds for real-time odds, scores, plays, and game-stat updates.
- [Multiplexed WebSocket](https://docs.therundown.io/guides/multiplexed-websocket.md): Subscribe to markets, scores, play-by-play, live game stats, and live game state over a single connection to /api/v2/ws.
- [V1 to V2 Migration Guide](https://docs.therundown.io/guides/v1-to-v2-migration.md): Understand the differences between V1 and V2 data models and migrate your application from the legacy lines format to the new markets-based system.
- [Efficient Polling](https://docs.therundown.io/guides/efficient-polling.md): Optimize data-point usage with delta endpoints, tight filters, smart polling intervals, and caching strategies.
- [Python SDK](https://docs.therundown.io/sdks/python.md): Use TheRundown API from Python with the requests library and websockets for real-time data.
- [JavaScript SDK](https://docs.therundown.io/sdks/javascript.md): Use TheRundown API from Node.js with Fetch and ws for real-time streaming.
- [Go SDK](https://docs.therundown.io/sdks/go.md): Use TheRundown API from Go with net/http for REST calls and gorilla/websocket for real-time streaming.

## OpenAPI Specs

- [openapi](/openapi.yaml)
- [openapi](/tools/chatgpt-actions/openapi.yaml)

## Optional

- [API Status](https://therundown.instatus.com)
- [Community](https://join.slack.com/t/therundownspace/shared_invite/zt-3t2aa3py9-pdPol0D6GfJHooxlx_mQIw)


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