TheRundown

https://docs.therundown.io/
Admin
TheRundown is a comprehensive sports API providing real-time odds from 15+ sportsbooks, live scores,...
Tokens:132,728
Snippets:932
Trust Score:8.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Python Libraries

Source: https://docs.therundown.io/sdks/python

Install the necessary Python libraries for making HTTP requests and establishing WebSocket connections.

```bash
pip install requests websockets
```

--------------------------------

### Install Gorilla WebSocket

Source: https://docs.therundown.io/sdks/go

Install the gorilla/websocket package for WebSocket support. No external dependencies are needed for REST calls.

```bash
go get github.com/gorilla/websocket
```

--------------------------------

### Example Usage Headers

Source: https://docs.therundown.io/rate-limits

These are example headers returned by the API, providing details on data points consumed, used, remaining, and the limit for the current billing window. It also indicates the tier, rate limit, and WebSocket access.

```text
X-Datapoints: 452
X-Datapoints-Used: 120348
X-Datapoints-Remaining: 1879652
X-Datapoints-Limit: 2000000
X-Datapoints-Period: monthly
X-Datapoints-Reset: 2026-03-31T00:00:00Z
X-Tier: starter
X-Rate-Limit: 2
X-Websocket-Access: false
```

--------------------------------

### Example JSON Response Structure

Source: https://docs.therundown.io/guides/player-props

This is an example of the JSON structure returned when fetching player prop data, showing market details and participant lines.

```json
{
  "market_id": 29,
  "name": "Player Points",
  "period_id": 0,
  "participants": [
    {
      "id": 12345,
      "name": "LeBron James Over",
      "type": "TYPE_OVER",
      "lines": [
        {
          "value": "25.5",
          "prices": {
            "19": { "price": -115, "is_main_line": true, "updated_at": "2026-02-12T18:30:00Z" },
            "23": { "price": -110, "is_main_line": true, "updated_at": "2026-02-12T18:29:45Z" }
          }
        }
      ]
    },
    {
      "id": 12345,
      "name": "LeBron James Under",
      "type": "TYPE_UNDER",
      "lines": [
        {
          "value": "25.5",
          "prices": {
            "19": { "price": -105, "is_main_line": true, "updated_at": "2026-02-12T18:30:00Z" },
            "23": { "price": -110, "is_main_line": true, "updated_at": "2026-02-12T18:29:45Z" }
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### Example Market Participants Response

Source: https://docs.therundown.io/api-reference/v2/markets

This is an example of the JSON structure returned for market participants. It includes participant IDs, types, and names.

```json
{
  "participants": [
    {
      "id": 70001,
      "market_event_id": 28401,
      "participant_id": 2005,
      "participant_type": "TYPE_PLAYER",
      "participant_name": "Donovan Mitchell",
      "updated_at": "2026-02-26T12:00:00Z"
    },
    {
      "id": 70002,
      "market_event_id": 28401,
      "participant_id": 2010,
      "participant_type": "TYPE_PLAYER",
      "participant_name": "Jalen Brunson",
      "updated_at": "2026-02-26T12:00:00Z"
    },
    {
      "id": 70003,
      "market_event_id": 28401,
      "participant_id": 51,
      "participant_type": "TYPE_TEAM",
      "participant_name": "Cleveland Cavaliers",
      "updated_at": "2026-02-26T12:00:00Z"
    },
    {
      "id": 70004,
      "market_event_id": 28401,
      "participant_id": 0,
      "participant_type": "TYPE_RESULT",
      "participant_name": "Over",
      "updated_at": "2026-02-26T12:00:00Z"
    }
  ]
}
```

--------------------------------

### Delta Polling Pattern Example

Source: https://docs.therundown.io/guides/v1-to-v2-migration

Example of how to use the delta polling pattern, focusing on the V2 markets delta.

```APIDOC
### Delta Polling Pattern

1. **Initial fetch**: Pass `last_id=0` (for markets delta) or a zeroed UUID for event deltas
2. **Store the cursor**: Each response includes a `last_id` or `delta_last_id` value
3. **Subsequent polls**: Pass the stored cursor to get only changes since your last poll
4. **Replace, don't merge**: Each delta contains the full updated object — replace your cached version entirely

```bash
# Most efficient: V2 markets delta
curl "https://therundown.io/api/v2/markets/delta?key=YOUR_API_KEY&last_id=0&sport_id=4&market_ids=1,2,3"
```
```

--------------------------------

### Market Definition Example Response

Source: https://docs.therundown.io/api-reference/v2/markets

An example of the JSON response structure when listing all market definitions.

```json
[
  {
    "id": 1,
    "name": "Money Line",
    "description": "Pick the winner of the game",
    "short_description": "Winner",
    "line_value_is_participant": false,
    "proposition": false,
    "period_id": 0,
    "live_variant_id": 41,
    "updated_at": "2025-01-15T12:00:00Z"
  },
  {
    "id": 2,
    "name": "Point Spread",
    "description": "Handicap betting on the margin of victory",
    "short_description": "Spread",
    "line_value_is_participant": false,
    "proposition": false,
    "period_id": 0,
    "live_variant_id": 42,
    "updated_at": "2025-01-15T12:00:00Z"
  },
  {
    "id": 3,
    "name": "Total Over/Under",
    "description": "Combined score of both teams",
    "short_description": "Total",
    "line_value_is_participant": false,
    "proposition": false,
    "period_id": 0,
    "live_variant_id": 43,
    "updated_at": "2025-01-15T12:00:00Z"
  },
  {
    "id": 29,
    "name": "Player Points",
    "description": "Player points scored in the game",
    "short_description": "Points",
    "line_value_is_participant": true,
    "proposition": true,
    "period_id": 0,
    "live_variant_id": 90,
    "updated_at": "2025-01-15T12:00:00Z"
  },
  {
    "id": 94,
    "name": "Team Total",
    "description": "Total points scored by a single team",
    "short_description": "Team Total",
    "line_value_is_participant": true,
    "proposition": false,
    "period_id": 0,
    "live_variant_id": 96,
    "updated_at": "2025-01-15T12:00:00Z"
  }
]
```

--------------------------------

### Get Events by Sport and Date (JavaScript)

Source: https://docs.therundown.io/api-reference/v2/events

This JavaScript code snippet fetches events for a given sport and date using the fetch API. It dynamically gets the current date and logs the team names for each event. This example assumes an async context.

```javascript
const today = new Date().toISOString().split("T")[0];
const resp = await fetch(
  `https://therundown.io/api/v2/sports/4/events/${today}?key=YOUR_API_KEY&market_ids=1,2,3&offset=300`
);
const data = await resp.json();

data.events.forEach((event) => {
  console.log(`${event.teams[0].name} @ ${event.teams[1].name}`);
});
```

--------------------------------

### Get Event Closing Prices with cURL

Source: https://docs.therundown.io/api-reference/v2/events

Retrieve the final market prices recorded before an event started using cURL. This endpoint is available after an event has begun or completed.

```bash
curl "https://therundown.io/api/v2/events/EVENT_ID/closing?key=YOUR_API_KEY&market_ids=1,2,3"
```

--------------------------------

### Configure API Constants and Variables

Source: https://docs.therundown.io/sdks/go

Set up constants for the base URL and WebSocket URL, and retrieve the API key from environment variables. Ensure THERUNDOWN_API_KEY is set.

```go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"time"
)

const (
	baseURL = "https://therundown.io/api/v2"
	wsURL   = "wss://therundown.io/api/v2/ws/markets"
)

var apiKey = os.Getenv("THERUNDOWN_API_KEY")
```

--------------------------------

### GET /api/v2/events/{eventID}/closing — Closing prices

Source: https://docs.therundown.io/api-reference/v2/events

Returns the final market prices recorded before event start (closing lines). Available only after an event has begun or completed.

```APIDOC
## GET /api/v2/events/{eventID}/closing

### Description
Returns the final market prices recorded before event start (closing lines). Available only after an event has begun or completed.

### Method
GET

### Endpoint
/api/v2/events/{eventID}/closing

### Query Parameters
- **key** (string) - Required - Your API key.
- **market_ids** (string) - Optional - Comma-separated list of market IDs to filter by.

### Request Example
```bash
curl "https://therundown.io/api/v2/events/EVENT_ID/closing?key=YOUR_API_KEY&market_ids=1,2,3"
```

### Response
#### Success Response (200)
- **event_id** (string) - The unique identifier for the event.
- **sport_id** (integer) - The ID of the sport.
- **markets** (array) - An array of market objects. (Structure is the same as in the opening prices response)

#### Response Example
(The response structure is the same as for `GET /api/v2/events/{eventID}/openers`, with prices reflecting the final recorded lines before the event started.)
```

```APIDOC
## GET /api/v2/events/{eventID}/closing (Python Example)

### Description
Example of how to fetch closing prices using Python.

### Method
GET

### Endpoint
/api/v2/events/{eventID}/closing

### Request Example
```python
import requests

resp = requests.get(
    "https://therundown.io/api/v2/events/EVENT_ID/closing",
    headers={"X-TheRundown-Key": "YOUR_API_KEY"},
    params={"market_ids": "1,2,3"}
)
closing = resp.json()
print(closing["markets"])
```
```

--------------------------------

### GET /api/v2/events/{eventID}/closing — Event Closing Lines

Source: https://docs.therundown.io/api-reference/v2/events

Retrieves the final betting lines for a specific event before it started. This is useful for historical analysis or understanding the market's final sentiment.

```APIDOC
## GET /api/v2/events/{eventID}/closing

### Description
Retrieves the final betting lines for a specific event before it started. This is useful for historical analysis or understanding the market's final sentiment.

### Method
GET

### Endpoint
/api/v2/events/{eventID}/closing

### Query Parameters
- **key** (string) - Required - Your API key.
- **market_ids** (string) - Optional - Comma-separated list of market IDs to filter results.

### Request Example
```
https://therundown.io/api/v2/events/EVENT_ID/closing?key=YOUR_API_KEY&market_ids=1,2,3
```

### Response
#### Success Response (200)
- **event_id** (string) - The unique identifier for the event.
- **sport_id** (integer) - The identifier for the sport.
- **markets** (array) - An array of market objects, each containing participant lines.
  - **id** (integer) - The market's internal ID.
  - **market_id** (integer) - The market's public ID.
  - **period_id** (integer) - The period identifier.
  - **name** (string) - The name of the market (e.g., "handicap").
  - **market_description** (string) - A description of the market.
  - **participants** (array) - An array of participant objects.
    - **id** (integer) - The participant's internal ID.
    - **type** (string) - The type of participant (e.g., "TYPE_TEAM").
    - **name** (string) - The name of the participant.
    - **lines** (array) - An array of line objects for the participant.
      - **id** (string) - The line's unique identifier.
      - **value** (string) - The line value (e.g., spread value).
      - **prices** (object) - An object containing price information for different odds formats.
        - **[odds_format_id]** (object) - Details for a specific odds format.
          - **id** (string) - The price ID.
          - **price** (integer) - The betting price.
          - **is_main_line** (boolean) - Indicates if this is the main line.
          - **updated_at** (string) - The timestamp when the line was last updated.

#### Response Example
```json
{
  "event_id": "401584701-d1f2-43e7-b5a6-9c8d7e6f5a4b",
  "sport_id": 4,
  "markets": [
    {
      "id": 28402,
      "market_id": 2,
      "period_id": 0,
      "name": "handicap",
      "market_description": "Spread: Win or lose by margin of points",
      "participants": [
        {
          "id": 51,
          "type": "TYPE_TEAM",
          "name": "Cleveland Cavaliers",
          "lines": [
            {
              "id": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
              "value": "-4.5",
              "prices": {
                "19": { "id": "194940001", "price": -108, "is_main_line": true, "updated_at": "2026-02-27T00:28:00Z" }
              }
            }
          ]
        },
        {
          "id": 56,
          "type": "TYPE_TEAM",
          "name": "New York Knicks",
          "lines": [
            {
              "id": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
              "value": "4.5",
              "prices": {
                "19": { "id": "194940002", "price": -112, "is_main_line": true, "updated_at": "2026-02-27T00:28:00Z" }
              }
            }
          ]
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Get Events by Sport and Date (Python)

Source: https://docs.therundown.io/api-reference/v2/events

This Python script fetches events for a given sport and date using the requests library. It includes necessary imports and demonstrates how to iterate through the response to print team names. Ensure you have the 'requests' library installed.

```python
import requests
from datetime import date

response = requests.get(
    f"https://therundown.io/api/v2/sports/4/events/{date.today()}",
    headers={"X-TheRundown-Key": "YOUR_API_KEY"},
    params={"market_ids": "1,2,3", "offset": "300"}
)

for event in response.json()["events"]:
    teams = event["teams"]
    print(f"{teams[0]['name']} @ {teams[1]['name']}")
```

--------------------------------

### V2 Markets Delta Endpoint Example

Source: https://docs.therundown.io/guides/v1-to-v2-migration

Demonstrates polling the V2 markets delta endpoint for the most granular and efficient price changes. Use 'last_id=0' for the initial fetch.

```bash
curl "https://therundown.io/api/v2/markets/delta?\ \
key=YOUR_API_KEY&last_id=0&sport_id=4&market_ids=1,2,3"
```

--------------------------------

### Fetch Markets by Event ID (Python)

Source: https://docs.therundown.io/guides/player-props

Python example to fetch markets for a specific event. Requires the 'requests' library. Iterates through the response to print market IDs and names.

```python
event_id = "EVENT_ID"
response = requests.get(
    f"{BASE_URL}/events/{event_id}/markets",
    params={"key": API_KEY}
)

for market in response.json():
    if market.get("proposition"):
        print(f"  {market['id']:>4}  {market['name']}")
```

--------------------------------

### Configuration Constants

Source: https://docs.therundown.io/sdks/javascript

Set up API key and base URLs for TheRundown API requests. Ensure your API key is securely stored, preferably using environment variables.

```javascript
const API_KEY = process.env.THERUNDOWN_API_KEY || "YOUR_API_KEY";
const BASE_URL = "https://therundown.io/api/v2";
const WS_URL = "wss://therundown.io/api/v2/ws/markets";
```

--------------------------------

### Example Response for Opening Prices

Source: https://docs.therundown.io/api-reference/v2/events

This JSON structure represents the opening prices for an event, showing market details and participant lines with their initial recorded prices.

```json
{
  "event_id": "401584701-d1f2-43e7-b5a6-9c8d7e6f5a4b",
  "sport_id": 4,
  "markets": [
    {
      "id": 28401,
      "market_id": 1,
      "period_id": 0,
      "name": "Moneyline",
      "market_description": "Pick the winner of the game",
      "participants": [
        {
          "id": 51,
          "type": "TYPE_TEAM",
          "name": "Cleveland Cavaliers",
          "lines": [
            {
              "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
              "value": "",
              "prices": {
                "19": { "id": "194910001", "price": -130, "is_main_line": true, "updated_at": "2026-02-24T14:00:00Z" }
              }
            }
          ]
        },
        {
          "id": 56,
          "type": "TYPE_TEAM",
          "name": "New York Knicks",
          "lines": [
            {
              "id": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
              "value": "",
              "prices": {
                "19": { "id": "194910002", "price": 110, "is_main_line": true, "updated_at": "2026-02-24T14:00:00Z" }
              }
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Fetch Events with Usage Headers

Source: https://docs.therundown.io/rate-limits

This `curl` command demonstrates how to fetch events while including your API key. It also shows example response headers that provide information about data point usage, tier, rate limits, and data delay.

```bash
curl -i -H "X-TheRundown-Key: YOUR_API_KEY" \
  "https://therundown.io/api/v2/sports/4/events/2026-02-26?market_ids=1,2,3&affiliate_ids=19,23&main_line=true&offset=300"
```

--------------------------------

### Python Polling Loop for Live Event Data

Source: https://docs.therundown.io/guides/efficient-polling

This example demonstrates how to fetch a full snapshot of events and then poll the market delta endpoint. It includes automatic fallback to a full refresh if the delta cursor becomes stale. Ensure you replace 'YOUR_API_KEY' with your actual API key.

```python
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://therundown.io/api/v2"
SPORT_ID = 4
MARKET_IDS = "1,2,3"
AFFILIATE_IDS = "19,23"
POLL_INTERVAL = 5  # seconds

# Local cache: event_id -> event data
events = {}

def fetch_full_snapshot():
    """Load the full event list and return the delta cursor."""
    resp = requests.get(
        f"{BASE}/sports/{SPORT_ID}/events/2026-02-26",
        headers={"X-TheRundown-Key": API_KEY},
        params={
            "market_ids": MARKET_IDS,
            "affiliate_ids": AFFILIATE_IDS,
            "main_line": "true",
            "offset": "300",
        }
    )
    data = resp.json()

    for event in data.get("events", []):
        events[event["event_id"]] = event

    cursor = data.get("meta", {}).get("delta_last_id", "0")
    print(f"Loaded {len(events)} events, cursor={cursor}")
    return cursor

def poll_market_delta(last_id):
    """Fetch price changes since last_id. Returns new cursor."""
    resp = requests.get(
        f"{BASE}/markets/delta",
        headers={"X-TheRundown-Key": API_KEY},
        params={
            "last_id": last_id,
            "sport_id": SPORT_ID,
            "market_ids": MARKET_IDS,
        }
    )

    if resp.status_code != 200:
        print(f"Delta error {resp.status_code}, re-bootstrapping...")
        return None  # Signal to re-bootstrap

    data = resp.json()
    changes = data.get("deltas", [])

    for change in changes:
        eid = change.get("event_id")
        print(
            f"Price change: {eid} {change.get('market_name')} "
            f"{change.get('participant_name')} -> {change.get('price')}"
        )

    new_cursor = data.get("meta", {}).get("delta_last_id", last_id)
    return new_cursor

# Bootstrap
cursor = fetch_full_snapshot()

# Poll loop
while True:
    time.sleep(POLL_INTERVAL)
    result = poll_market_delta(cursor)

    if result is None:
        # Cursor went stale, re-bootstrap
        cursor = fetch_full_snapshot()
    else:
        cursor = result

```

--------------------------------

### Connect to WebSocket API (Python)

Source: https://docs.therundown.io/api-reference/v2/websocket

Connect to The Rundown WebSocket API using Python's 'websockets' library. Replace 'YOUR_API_KEY' with your key. This example demonstrates receiving and processing market data, skipping heartbeats.

```python
import asyncio
import json
import websockets

API_KEY = "YOUR_API_KEY"
URL = f"wss://therundown.io/api/v2/ws/markets?key={API_KEY}&sport_ids=4"

async def listen():
    async with websockets.connect(URL) as ws:
        print("Connected to TheRundown WebSocket")
        async for message in ws:
            msg = json.loads(message)

            if msg.get("meta", {}).get("type") == "heartbeat":
                continue

            d = msg["data"]
            print(
                f"Event {d['event_id']} | market={d['market_id']} aff={d['affiliate_id']}"
            )
            print(
                f"  line={d['line']} price={d['price']}"
                f" (was {d['previous_price']}, delta={d['price_delta']})"
            )

asyncio.run(listen())

```

--------------------------------

### Example Odds History Response

Source: https://docs.therundown.io/api-reference/v2/markets

This is an example of the JSON structure returned for historical odds data. It includes details about market lines, prices, and changes over time.

```json
{
  "meta": {
    "count": 5
  },
  "history": [
    {
      "id": 90001,
      "market_line_price_id": 12345,
      "event_id": "401584701-d1f2-43e7-b5a6-9c8d7e6f5a4b",
      "sport_id": 4,
      "affiliate_id": 19,
      "market_participant_id": 51,
      "market_id": 2,
      "line": "-3.5",
      "price": "-110",
      "previous_price": "",
      "change_type": "new",
      "closed_at": "",
      "updated_at": "2026-02-24T14:00:00Z"
    },
    {
      "id": 90002,
      "market_line_price_id": 12345,
      "event_id": "401584701-d1f2-43e7-b5a6-9c8d7e6f5a4b",
      "sport_id": 4,
      "affiliate_id": 19,
      "market_participant_id": 51,
      "market_id": 2,
      "line": "-3.5",
      "price": "-115",
      "previous_price": "-110",
      "change_type": "price_change",
      "closed_at": "",
      "updated_at": "2026-02-25T18:30:00Z"
    },
    {
      "id": 90003,
      "market_line_price_id": 12345,
      "event_id": "401584701-d1f2-43e7-b5a6-9c8d7e6f5a4b",
      "sport_id": 4,
      "affiliate_id": 19,
      "market_participant_id": 51,
      "market_id": 2,
      "line": "-4.5",
      "price": "-110",
      "previous_price": "-115",
      "change_type": "line_change",
      "closed_at": "",
      "updated_at": "2026-02-26T01:15:00Z"
    },
    {
      "id": 90004,
      "market_line_price_id": 67890,
      "event_id": "401584701-d1f2-43e7-b5a6-9c8d7e6f5a4b",
      "sport_id": 4,
      "affiliate_id": 19,
      "market_participant_id": 56,
      "market_id": 1,
      "line": "",
      "price": "110",
      "previous_price": "",
      "change_type": "new",
      "closed_at": "",
      "updated_at": "2026-02-24T14:00:00Z"
    },
    {
      "id": 90005,
      "market_line_price_id": 67890,
      "event_id": "401584701-d1f2-43e7-b5a6-9c8d7e6f5a4b",
      "sport_id": 4,
      "affiliate_id": 19,
      "market_participant_id": 56,
      "market_id": 1,
      "line": "",
      "price": "122",
      "previous_price": "110",
      "change_type": "price_change",
      "closed_at": "",
      "updated_at": "2026-02-25T22:00:00Z"
    }
  ]
}
```

--------------------------------

### V2 API Response Structure Example

Source: https://docs.therundown.io/guides/getting-live-odds

A condensed JSON example of a V2 API response for a single event, illustrating the nested structure of events, scores, teams, and markets.

```json
{
  "events": [
    {
      "event_id": "abc123",
      "sport_id": 4,
      "score": {
        "event_status": "STATUS_IN_PROGRESS",
        "score_away": 62,
        "score_home": 55,
        "display_clock": "4:32",
        "game_period": 2,
        "event_status_detail": "4:32 - 2nd",
        "updated_at": "2026-02-12T18:30:00Z"
      },
      "teams": [
        { "team_id": 1, "name": "Boston Celtics" },
        { "team_id": 2, "name": "Los Angeles Lakers" }
      ],
      "markets": [
        {
          "market_id": 1,
          "name": "Moneyline",
          "period_id": 0,
          "participants": [
            {
              "id": 1,
              "type": "TYPE_TEAM",
              "name": "Boston Celtics",
              "lines": [
                {
                  "value": "",
                  "prices": {
                    "19": { "price": -150, "is_main_line": true, "updated_at": "2026-02-12T18:30:00Z" },
                    "23": { "price": -145, "is_main_line": true, "updated_at": "2026-02-12T18:28:00Z" }
                  }
                }
              ]
            },
            {
              "id": 2,
              "type": "TYPE_TEAM",
              "name": "Los Angeles Lakers",
              "lines": [
                {
                  "value": "",
                  "prices": {
                    "19": { "price": 130, "is_main_line": true, "updated_at": "2026-02-12T18:30:00Z" },
                    "23": { "price": 125, "is_main_line": true, "updated_at": "2026-02-12T18:28:00Z" }
                  }
                }
              ]
            }
          ]
        },
        {
          "market_id": 2,
          "name": "Point Spread",
          "period_id": 0,
          "participants": [
            {
              "id": 1,
              "type": "TYPE_TEAM",
              "name": "Boston Celtics",
              "lines": [
                {
                  "value": "-3.5",
                  "prices": {
                    "19": { "price": -110, "is_main_line": true, "updated_at": "2026-02-12T18:30:00Z" }
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Connect to Markets WebSocket

Source: https://docs.therundown.io/api-reference/generated/v2-websocket/markets-websocket-%E2%80%94-stream-real-time-market-price-updates

Use this WebSocket URL to establish a connection for streaming V2 market price changes. Replace YOUR_API_KEY with your actual API key.

```bash
wss://therundown.io/api/v2/ws/markets?key=YOUR_API_KEY
```

--------------------------------

### Configure MCP Server in mcp.json (Cursor)

Source: https://docs.therundown.io/mcp

Add this configuration to your `mcp.json` file in Cursor to connect to the MCP server. This enables AI assistants to access API documentation.

```json
{
  "mcpServers": {
    "therundown": {
      "url": "https://docs.therundown.io/mcp"
    }
  }
}
```

--------------------------------

### GET /api/v2/markets/delta — Market delta polling

Source: https://docs.therundown.io/api-reference/v2/markets

Fetches real-time changes in market line prices. This endpoint is designed for polling to get the latest updates since the last request.

```APIDOC
## GET /api/v2/markets/delta

### Description
Fetches real-time changes in market line prices. This endpoint is designed for polling to get the latest updates since the last request.

### Method
GET

### Endpoint
https://therundown.io/api/v2/markets/delta

### Parameters
#### Query Parameters
- **key** (string) - Required - Your API key.
- **last_id** (integer) - Optional - The ID of the last market line price received. Used for subsequent polls to get only new changes.
- **sport_id** (integer) - Required - The ID of the sport to filter by.
- **market_ids** (string) - Optional - A comma-separated list of market IDs to filter by.
- **event_id** (string) - Query - Filter by event ID.
- **limit** (integer) - Query - Max results (default 1000, max 5000).

### Request Example
```bash
curl "https://therundown.io/api/v2/markets/delta?key=YOUR_API_KEY&last_id=0&sport_id=4&market_ids=1,2,3"
```

### Response
#### Success Response (200)
- **meta** (object)
  - **delta_last_id** (string) - The ID of the last market line price in the current response.
  - **count** (integer) - The number of deltas returned.
  - **has_more** (boolean) - Indicates if there are more changes available.
- **deltas** (array)
  - **id** (integer) - Unique identifier for the market line price change.
  - **event_id** (string) - The ID of the event associated with this market.
  - **sport_id** (integer) - The ID of the sport.
  - **affiliate_id** (integer) - The ID of the affiliate.
  - **market_id** (integer) - The ID of the market.
  - **market_name** (string) - The name of the market.
  - **participant_id** (integer) - The ID of the participant.
  - **participant_type** (string) - The type of participant (e.g., TYPE_TEAM, TYPE_RESULT).
  - **participant_name** (string) - The name of the participant.
  - **line** (string) - The line for the market (e.g., spread, total).
  - **price** (string) - The current price for this market line.
  - **previous_price** (string) - The previous price for this market line.
  - **change_type** (string) - The type of change that occurred (e.g., price_change).
  - **closed_at** (string) - Timestamp when the market was closed.
  - **updated_at** (string) - Timestamp when the market line price was last updated.

#### Response Example
```json
{
  "meta": {
    "delta_last_id": "584012",
    "count": 3,
    "has_more": false
  },
  "deltas": [
    {
      "id": 584010,
      "event_id": "401584701-d1f2-43e7-b5a6-9c8d7e6f5a4b",
      "sport_id": 4,
      "affiliate_id": 19,
      "market_id": 2,
      "market_name": "Point Spread",
      "participant_id": 51,
      "participant_type": "TYPE_TEAM",
      "participant_name": "Cleveland Cavaliers",
      "line": "-4.5",
      "price": "-110",
      "previous_price": "-105",
      "change_type": "price_change",
      "closed_at": "",
      "updated_at": "2026-02-26T18:45:30Z"
    }
  ]
}
```
```

--------------------------------

### GET /api/v2/markets/participants — Get market participants

Source: https://docs.therundown.io/api-reference/v2/markets

Returns participants (teams, players, or result types like Over/Under) for specified markets and events. Useful for resolving participant IDs to names.

```APIDOC
## GET /api/v2/markets/participants

### Description
Returns participants (teams, players, or result types like Over/Under) for specified markets and events. Useful for resolving participant IDs to names.

### Method
GET

### Endpoint
/api/v2/markets/participants

### Parameters
#### Query Parameters
- **market_ids** (query) - Optional - Comma-separated market IDs
- **event_id** (query) - Optional - Filter by event ID

### Request Example
```bash
curl "https://therundown.io/api/v2/markets/participants?key=YOUR_API_KEY&event_id=EVENT_ID&market_ids=29"
```

### Response
#### Success Response (200)
- **participants** (array) - List of market participants
  - **id** (integer) - Unique identifier for the participant record
  - **market_event_id** (integer) - The ID of the event this market belongs to
  - **participant_id** (integer) - The ID of the participant (team, player, etc.)
  - **participant_type** (string) - Type of participant (e.g., TYPE_PLAYER, TYPE_TEAM, TYPE_RESULT)
  - **participant_name** (string) - Name of the participant
  - **updated_at** (string) - Timestamp of the last update

#### Response Example
```json
{
  "participants": [
    {
      "id": 70001,
      "market_event_id": 28401,
      "participant_id": 2005,
      "participant_type": "TYPE_PLAYER",
      "participant_name": "Donovan Mitchell",
      "updated_at": "2026-02-26T12:00:00Z"
    },
    {
      "id": 70002,
      "market_event_id": 28401,
      "participant_id": 2010,
      "participant_type": "TYPE_PLAYER",
      "participant_name": "Jalen Brunson",
      "updated_at": "2026-02-26T12:00:00Z"
    },
    {
      "id": 70003,
      "market_event_id": 28401,
      "participant_id": 51,
      "participant_type": "TYPE_TEAM",
      "participant_name": "Cleveland Cavaliers",
      "updated_at": "2026-02-26T12:00:00Z"
    },
    {
      "id": 70004,
      "market_event_id": 28401,
      "participant_id": 0,
      "participant_type": "TYPE_RESULT",
      "participant_name": "Over",
      "updated_at": "2026-02-26T12:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Configure API Key and Base URLs

Source: https://docs.therundown.io/sdks/python

Set up your API key and define the base URLs for REST and WebSocket endpoints. It's recommended to use environment variables for your API key.

```python
import os

API_KEY = os.environ.get("THERUNDOWN_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://therundown.io/api/v2"
WS_URL = "wss://therundown.io/api/v2/ws/markets"

HEADERS = {
    "X-TheRundown-Key": API_KEY,
}
```

--------------------------------

### Fetch Events with Markets (V2 Recommended)

Source: https://docs.therundown.io/guides/v1-to-v2-migration

Use this V2 Python code to fetch events and access detailed market data, including player props and alternate lines. It requires an API key and allows filtering by market and affiliate IDs.

```python
import requests

API_KEY = "YOUR_API_KEY"

# V2: Fetch events with markets
response = requests.get(
    "https://therundown.io/api/v2/sports/4/events/2026-02-12",
    params={
        "key": API_KEY,
        "market_ids": "1,2,3",
        "affiliate_ids": "19",
    }
)
data = response.json()

for event in data["events"]:
    away = event["teams"][0]["name"]
    home = event["teams"][1]["name"]
    print(f"{away} @ {home}")

    for market in event.get("markets", []):
        mid = market["market_id"]
        period = market.get("period_id", 0)

        period_label = "" if period == 0 else f" (Period {period})"
        print(f"  {market['name']}{period_label}:")

        for participant in market["participants"]:
            for line in participant["lines"]:
                price_obj = line["prices"].get("19", {})
                price = price_obj.get("price", "N/A")
                line_val = line.get("value", "")
                line_str = f" {line_val}" if line_val else ""
                print(f"    {participant['name']}{line_str}: {price}")
```

--------------------------------

### Fetch All Sport Openers with Python

Source: https://docs.therundown.io/guides/historical-odds

Fetches and processes opening lines for all events of a sport on a given date using Python. Includes parsing event and market data.

```python
# All openers for a sport + date
response = requests.get(
    f"{BASE_URL}/sports/{sport_id}/openers/{today}",
    params={
        "key": API_KEY,
        "market_ids": "1,2,3",
        "affiliate_ids": "19,23",
        "offset": "300",
    }
)

# Response is { "events": [ { "markets": [...] } ] }
for event in response.json().get("events", []):
    away = event["teams"][0]["name"]
    home = event["teams"][1]["name"]
    print(f"\n{away} @ {home}")
    for market in event.get("markets", []):
        print(f"  {market['name']} (opened)")
        for participant in market["participants"]:
            for line in participant["lines"]:
                for aff_id, price in line["prices"].items():
                    print(f"    {participant['name']}: {line['value']} {price['price']}")
```

--------------------------------

### GET /api/v2/events/{event_id}/markets

Source: https://docs.therundown.io/guides/building-odds-screen

Returns only the markets available for a specific event. Useful when building a detail view for a single game. Use the `event_id` value returned by `GET /api/v2/sports/{sportID}/events/{date}` when calling per-event V2 endpoints.

```APIDOC
## GET /api/v2/events/{event_id}/markets

### Description
Returns only the markets available for a specific event. Useful when building a detail view for a single game.

### Method
GET

### Endpoint
/api/v2/events/{event_id}/markets

### Query Parameters
- **key** (string) - Required - Your API key.

### Parameters
#### Path Parameters
- **event_id** (string) - Required - The ID of the event for which to retrieve markets. This ID can be obtained from the `GET /api/v2/sports/{sportID}/events/{date}` endpoint.

### Request Example
```bash
curl "https://therundown.io/api/v2/events/EVENT_ID/markets?key=YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **id** (integer) - Numeric market ID.
- **name** (string) - Human-readable name of the market (e.g., "Moneyline", "Player Points").
- **proposition** (boolean) - `true` for player prop markets, `false` for game-level markets.
- **period_id** (integer) - The period this market applies to (full game, first half, etc.).
- **live_variant_id** (integer) - If set, the corresponding live/in-play market ID.
- **description** (string) - A longer description of the market.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Moneyline",
    "proposition": false,
    "period_id": 1,
    "live_variant_id": null,
    "description": "Winner of the game"
  },
  {
    "id": 2,
    "name": "Spread",
    "proposition": false,
    "period_id": 1,
    "live_variant_id": null,
    "description": "Point spread for the game"
  }
]
```
```

--------------------------------

### Helper Function for API GET Requests

Source: https://docs.therundown.io/sdks/go

A utility function to make GET requests to the API, handling URL parsing, query parameter encoding (including the API key), response status checks, and rate limiting. It reads and returns the response body.

```go
func apiGet(path string, params map[string]string) ([]byte, error) {
	u, err := url.Parse(baseURL + path)
	if err != nil {
		return nil, err
	}

	q := u.Query()
	q.Set("key", apiKey)
	for k, v := range params {
		q.Set(k, v)
	}
	u.RawQuery = q.Encode()

	resp, err := http.Get(u.String())
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	if resp.StatusCode == http.StatusTooManyRequests {
		retryAfter := resp.Header.Get("Retry-After")
		if retryAfter == "" {
			retryAfter = "60"
		}
		return nil, fmt.Errorf("rate limited, retry after %s seconds", retryAfter)
	}

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("API error: %d %s", resp.StatusCode, resp.Status)
	}

	return io.ReadAll(resp.Body)
}
```

--------------------------------

### Connect to WebSocket API (JavaScript Browser/Node.js)

Source: https://docs.therundown.io/api-reference/v2/websocket

Connect to The Rundown WebSocket API to receive real-time market data. Ensure you replace 'YOUR_API_KEY' with your actual API key. This example handles connection, message reception, errors, and disconnections.

```javascript
const ws = new WebSocket(
    "wss://therundown.io/api/v2/ws/markets?key=YOUR_API_KEY&sport_ids=4&market_ids=1,2,3"
  );

  ws.onopen = () => {
    console.log("Connected to TheRundown WebSocket");
  };

  ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);

    // Skip heartbeats
    if (msg.meta?.type === "heartbeat") return;

    const d = msg.data;
    console.log(
      `Event ${d.event_id} | market=${d.market_id} aff=${d.affiliate_id}`
    );
    console.log(
      `  line=${d.line} price=${d.price} (was ${d.previous_price}, delta=${d.price_delta})`
    );
  };

  ws.onerror = (error) => {
    console.error("WebSocket error:", error);
  };

  ws.onclose = (event) => {
    console.log(`Disconnected: code=${event.code} reason=${event.reason}`);
    // Implement reconnection logic here
  };
  
```

--------------------------------

### Helper Function for API GET Requests

Source: https://docs.therundown.io/sdks/javascript

A utility function to simplify making GET requests to TheRundown API. It handles URL construction, API key inclusion, parameter appending, and basic error handling for rate limits and general API errors.

```javascript
async function apiGet(path, params = {}) {
  const url = new URL(`${BASE_URL}${path}`);
  url.searchParams.set("key", API_KEY);
  for (const [key, value] of Object.entries(params)) {
    url.searchParams.set(key, value);
  }

  const response = await fetch(url.toString());

  if (response.status === 429) {
    throw new Error("Rate limited. Check Retry-After header.");
  }

  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${response.statusText}`);
  }

  return response.json();
}
```
Tokens:
Raw