> ## 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.

# Events (V1)

> V1 legacy events with line-based odds, openers, closing, and schedules

> [!WARNING]
>
> V1 endpoints use a **line-based data model** (`lines` / `line_periods`) instead of the market-based model in V2. V1 is still fully supported, but new features and market types are V2-only. For new integrations, use [V2 Events](https://docs.therundown.io/api-reference/v2/events) instead.

> [!NOTE]
>
> V1 REST `GET` endpoints that return odds accept the optional `odds_format` query parameter. It defaults to `american`; see [Choose an odds format](https://docs.therundown.io/guides/odds-formats.md) for supported values and which response fields change.

## V1 vs V2 Data Model

| Concept | V1 | V2 |
| - | - | - |
| Odds structure | `lines` object with `moneyline`, `spread`, `total` fields | `markets` array with participants, lines, and prices |
| Period data | `line_periods` map keyed by affiliate ID, then period key | Separate market IDs for each period |
| All periods | `include=all_periods` query param | Explicit `market_ids` for period markets |
| Player props | Not supported | Supported via market IDs (29, 35, 39, etc.) |

***

> [!NOTE]
>
> Store your key in the `THERUNDOWN_API_KEY` environment variable and send it in the `X-TheRundown-Key` header. Legacy query authentication remains available for compatibility; use [header authentication](https://docs.therundown.io/authentication.md) for new integrations. Do not put keys in URLs.

## Endpoints

> [accordion] GET /api/v1/events/\{eventId} — Get a single event
>
> Returns a single event with V1 line data (moneyline, spread, total per affiliate).
>
> ### Parameters
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `eventId` | path | Yes | Event ID from the `event_id` field of event responses. An `event_uuid` value returns 404. |
> | `include` | query | No | Set to `all_periods` to include first-half, second-half, and period-specific lines |
> | `affiliate_ids` | query | No | Comma-separated sportsbook IDs |
>
> ```bash cURL theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/events/EVENT_ID"
> ```
>
> ```bash With all periods theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/events/EVENT_ID?include=all_periods"
> ```
>
> ```bash Specific sportsbooks theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/events/EVENT_ID?affiliate_ids=19,23"
> ```

> [accordion] GET /api/v1/sports/\{sportID}/events/\{date} — Events by sport and date
>
> Returns all events for a sport on a date with V1 line data.
>
> ### Parameters
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `sportID` | path | Yes | Sport ID (e.g., `4` for NBA) |
> | `date` | path | Yes | Date in `YYYY-MM-DD` format |
> | `offset` | query | No | UTC offset in **minutes** for the date boundary. US Central is `300` during daylight saving time (CDT) and `360` during standard time (CST). |
> | `affiliate_ids` | query | No | Comma-separated sportsbook IDs |
> | `conference_id` | query | No | Filter by conference ID |
> | `division_id` | query | No | Filter by division ID |
> | `exclude_status` | query | No | Comma-separated event statuses to exclude |
> | `include` | query | No | Set to `all_periods` for period-specific lines |
>
> ```bash cURL theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/events/2026-02-12?offset=300"
> ```
>
> ```bash With offset and period data theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/events/2026-02-12?offset=300&include=all_periods"
> ```
>
> ```bash Exclude canceled or postponed events theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/events/2026-02-12?offset=300&exclude_status=STATUS_CANCELED,STATUS_POSTPONED"
> ```
>
> ```python Python theme={null}
> import os
> import requests
> from datetime import date
>
> api_key = os.environ.get("THERUNDOWN_API_KEY")
> if not api_key:
>     raise RuntimeError("Set THERUNDOWN_API_KEY")
>
> resp = requests.get(
>     f"https://therundown.io/api/v1/sports/4/events/{date.today()}",
>     headers={"X-TheRundown-Key": api_key},
>     params={"include": "all_periods", "offset": "300"},
>     timeout=20,
> )
> resp.raise_for_status()
>
> for event in resp.json().get("events", []):
>     home = event["teams_normalized"][1]["name"]
>     away = event["teams_normalized"][0]["name"]
>     print(f"{away} @ {home}")
>
>     # With include=all_periods, lines may be null or omitted.
>     for aff_id, periods in (event.get("line_periods") or {}).items():
>         for period, line_data in periods.items():
>             ml = line_data.get("moneyline", {})
>             print(
>                 f"  Book {aff_id} ({period}): "
>                 f"{ml.get('moneyline_away')} / {ml.get('moneyline_home')}"
>             )
> ```

> [accordion] GET /api/v1/sports/\{sportID}/openers/\{date} — Opening lines
>
> Returns events with the earliest recorded V1 line data (opening lines) for a sport and date.
>
> ### Parameters
>
> Same as the events-by-sport-and-date endpoint above.
>
> ```bash cURL theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/openers/2026-02-12"
> ```
>
> ```bash With all periods theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/openers/2026-02-12?include=all_periods"
> ```

> [accordion] GET /api/v1/sports/\{sportID}/closing/\{date} — Closing lines
>
> Returns events with the final V1 line data recorded before event start.
>
> ```bash cURL theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/closing/2026-02-12"
> ```
>
> ```bash With all periods theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/closing/2026-02-12?include=all_periods"
> ```

> [accordion] GET /api/v1/sports/\{sportID}/schedule — Event schedule
>
> Returns the event schedule for a sport with cursor-based pagination. Useful for loading upcoming games, filtering by team, conference, or division.
>
> ### Parameters
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `sportID` | path | Yes | Sport ID |
> | `limit` | query | No | Max results (default 50) |
> | `last_event_uuid` | query | No | Cursor for pagination -- pass the last event UUID from the previous page |
> | `from` | query | No | Start date (YYYY-MM-DD) |
> | `season_year` | query | No | Filter by season year |
> | `season_type_id` | query | No | Filter by season type |
> | `team_id` | query | No | Filter to a specific team |
> | `conference_id` | query | No | Filter by conference |
> | `division_id` | query | No | Filter by division |
> | `include` | query | No | Set to `teams` to add `away_team_detail` and `home_team_detail` objects to each entry |
> | `sort` | query | No | Sort order: `asc` (default) or `desc` |
>
> ```bash Upcoming NBA schedule theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/schedule?limit=20&sort=asc"
> ```
>
> ```bash Schedule for a specific team theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/schedule?team_id=24&include=teams"
> ```
>
> ```bash Paginated schedule (page 2) theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/sports/4/schedule?last_event_uuid=LAST_UUID_FROM_PAGE_1&limit=50"
> ```
>
> > [!NOTE]
> >
> > MLB schedule rows include `game_number` (`1` or `2` for a true doubleheader) and `game_type` (`doubleheader`, `makeup`, or `doubleheader_makeup`). Both are omitted for ordinary games.

***

## V1 Line Structure

In V1 responses, each event contains a `lines` object keyed by `affiliate_id`. Each affiliate's line object has:

```json theme={null}
{
  "lines": {
    "19": {
      "moneyline": {
        "moneyline_away": 150,
        "moneyline_home": -175
      },
      "spread": {
        "point_spread_away": 4.5,
        "point_spread_away_money": -110,
        "point_spread_home": -4.5,
        "point_spread_home_money": -110
      },
      "total": {
        "total_over": 220.5,
        "total_over_money": -110,
        "total_under": 220.5,
        "total_under_money": -110
      }
    }
  }
}
```

When `include=all_periods` is used, `lines` may be omitted or `null`. Read period-specific data from `line_periods`, grouped by affiliate ID and then period key:

```json theme={null}
{
  "line_periods": {
    "19": {
      "period_full_game": {
        "moneyline": {
          "moneyline_away": 150,
          "moneyline_home": -175
        },
        "spread": {
          "point_spread_away": 4.5,
          "point_spread_home": -4.5
        },
        "total": {
          "total_over": 220.5,
          "total_under": 220.5
        }
      },
      "period_first_half": {
        "moneyline": {
          "moneyline_away": 120,
          "moneyline_home": -140
        }
      }
    }
  }
}
```


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