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

# One Schema With Stable Event, Player and Team IDs

> How events, markets, participants, lines, and prices relate to each other in the V2 API.

The V2 API organizes sports data in a nested hierarchy. Understanding this structure is essential for parsing event responses, building odds screens, and processing delta updates. For how the model supports comparing prices across books, see the [sports odds API guide](https://therundown.io/sports-odds-api).

## Hierarchy Overview

```
Event
├── score                    # Live score, game clock, status
├── teams[]                  # Away team (index 0), Home team (index 1)
├── schedule                 # Season info, event name
└── markets[]                # Array of market types
      ├── market_id          # e.g., 1 = Moneyline, 2 = Spread, 3 = Total
      ├── period_id          # 0 = full game, 1 = first half, etc.
      └── participants[]     # Teams, players, or result types
            ├── id           # Participant identifier
            ├── type         # TYPE_TEAM, TYPE_PLAYER, or TYPE_RESULT
            └── lines[]      # Available lines for this participant
                  ├── id     # 32-character hex line identifier
                  ├── value  # Line value (e.g., "-3.5"); omitted when empty
                  └── prices # Map of affiliate_id → price object
                        {affiliate_id}:
                          ├── id            # Numeric string price identifier
                          ├── price         # American odds (e.g., -110, +150)
                          ├── is_main_line  # Main-line flag for this affiliate's quote
                          └── updated_at    # ISO 8601 timestamp
```

## Event completion for grading

For events with game-stat coverage, `meta.complete: true` marks the event's box score finalized for grading. REST exposes this event-level signal on each team or player stats group from `/api/v2/events/{eventID}/stats` or `/api/v2/events/{eventID}/players/stats`, paired with `meta.event_id`. It is not a field on the ordinary event object or the events response envelope. WebSocket `game_stats` messages use `data.complete` and `data.event_id` for the same event-level signal. See [Event completion for grading](https://docs.therundown.io/guides/scores-and-results.md#event-completion-for-grading) for examples, access requirements, and handling of missing completion or later corrections.

## Event Object

Each event represents a single game or match. Events are the top-level objects returned by `/api/v2/sports/{sportID}/events/{date}`.

| Field | Type | Description |
| - | - | - |
| `event_id` | string | Canonical event identifier string. Use this value in V2 path params, filters, delta consumers, and cache keys. |
| `sport_id` | integer | Sport identifier. See [Sport IDs](https://docs.therundown.io/reference/sports.md). |
| `event_uuid` | string | Compatibility identifier retained for older integrations. Do not assume it matches `event_id`. |
| `event_date` | string | Scheduled start time in ISO 8601 UTC |
| `rotation_number_away` | integer | Away team rotation number (not used for soccer) |
| `rotation_number_home` | integer | Home team rotation number (not used for soccer) |
| `score` | object | Live score and game status. See [Score Object](#score-object) below. |
| `teams` | array | Two-element array: `[away_team, home_team]`. See [Team Object](#team-object) below. |
| `schedule` | object | Season metadata: `season_type`, `season_year`, `event_name`, `league_name` |
| `markets` | array | Array of [Market objects](#market-object) with odds data |
| `affiliate_source_ids` | object | Map of affiliate ID (string) → that sportsbook's own identifier for this event, when available. See [Source identifiers](https://docs.therundown.io/reference/sportsbooks.md#source-identifiers-mapping-to-a-book%E2%80%99s-own-data). |
| `teams_normalized` | array | The same team objects as `teams`, repeated under the V1 field name for V1-to-V2 migration parity |
| `affiliate_deep_links` | object | Navigation URLs keyed by affiliate ID (as a string). Each URL is the event's page on that sportsbook unless `affiliate_deep_link_types` marks it as a catalog fallback. Omitted when no links are available. |
| `affiliate_deep_link_types` | object | Route type for entries in `affiliate_deep_links`, keyed by affiliate ID. `catalog` marks a validated sportsbook catalog page used as a fallback; an affiliate ID absent from this map has an event-page URL. |
| `live_game_state` | object | Real-time game state for live events: period, clock, last play and a sport-specific block. Requires the live game state entitlement (Ultra plan or higher); keys without it never receive this field. |

> [!NOTE]
>
> For V2 REST endpoints and WebSocket filters, pass the `event_id` value returned in event payloads. Do not substitute `event_uuid`.

### Score Object

| Field | Type | Description |
| - | - | - |
| `event_status` | string | Current status (e.g., `STATUS_SCHEDULED`, `STATUS_IN_PROGRESS`, `STATUS_FINAL`). See [Event Statuses](https://docs.therundown.io/reference/event-statuses.md). |
| `score_away` | integer | Away team score |
| `score_home` | integer | Home team score |
| `score_away_by_period` | array | Away team's per-period scores, not running totals; index `0` is the first period. Overtime periods are appended. Read this array by its own length. Its sum is not guaranteed to equal `score_away`; verify before using it. |
| `score_home_by_period` | array | Home team's per-period scores, not running totals; index `0` is the first period. Overtime periods are appended. Read this array by its own length. Its sum is not guaranteed to equal `score_home`; verify before using it. |
| `venue_name` | string | Arena or stadium name. May be an empty string when unavailable. |
| `venue_location` | string | City and state. May be an empty string when unavailable. |
| `game_clock` | integer | Game clock in seconds |
| `display_clock` | string | Formatted clock display (e.g., "4:32") |
| `game_period` | integer | Current period number |
| `broadcast` | string | TV broadcast network |
| `event_status_detail` | string | Human-readable status (e.g., "3rd Quarter - 4:32") |
| `updated_at` | string | ISO 8601 timestamp of the last score update |
| `event_id` | string | The event's `event_id` |
| `team_id_away` | integer | Away team ID. Omitted when zero. |
| `team_id_home` | integer | Home team ID. Omitted when zero. |
| `winner_away` | integer | `1` when the away team won a final game; otherwise `0` |
| `winner_home` | integer | `1` when the home team won a final game; otherwise `0` |

> [!NOTE]
>
> Score metadata can be incomplete. Text fields such as `venue_name`, `venue_location`, `broadcast`, and `display_clock` may be empty when unavailable. Period arrays can also be empty. Use `score.updated_at` to judge freshness.

Regulation NFL and NBA finals have four period entries per side and `game_period` of `4`. Each overtime adds another entry and advances `game_period`: one overtime gives five entries and `Final/OT`; two give six entries and `Final/2OT`. Regulation finals use `event_status_detail` of `Final`. Exhibition exceptions are described below.

Read each side by its own array length. In baseball, the home array is one entry shorter when the home team does not bat in the bottom of the ninth or the last extra inning. Do not pad a missing entry with zero or assume both arrays have the same length.

> [!NOTE]
>
> The final scores (`score_home` and `score_away`) and period arrays are independent fields. In the twelve months reviewed on September 8, 2026, every NFL and NBA event that reached a final state had period sums matching its final scores. `game_period` matched the array lengths in all but one exhibition game. These are observations, not enforced guarantees: verify completeness, each side's sum, and the period count before deriving a result, and handle mismatches without guessing.
>
> All-Star and preseason games can be final with an empty period array or `game_period` of `0` or `1`. Regular-season and playoff games were consistent in that review, but still need validation. Exclude preseason using the [season-specific sport IDs](https://docs.therundown.io/reference/sports.md#season-specific-sports), including NBA Preseason (`23`) and NFL Preseason (`25`).

See [Scores and Results](https://docs.therundown.io/guides/scores-and-results.md) for worked examples, half scores, and checks before locking a result.

### Team Object

| Field | Type | Description |
| - | - | - |
| `team_id` | integer | Normalized team identifier (stable across seasons and endpoints) |
| `name` | string | Full team name (e.g., "Cleveland Cavaliers") |
| `mascot` | string | Team mascot (e.g., "Cavaliers") |
| `abbreviation` | string | Short abbreviation (e.g., "CLE") |
| `record` | string | Current season record (e.g., "42-14") |
| `is_away` | boolean | `true` if this is the away team |
| `is_home` | boolean | `true` if this is the home team |
| `ranking` | integer | Poll ranking (`1` to `25`) for ranked teams, as in NCAA Football; `99` means unranked and `0` means the sport has no ranking |
| `conference_id` | integer | Conference ID, when the team belongs to one |
| `conference` | object | Conference details (`conference_id`, `sport_id`, `name`, and `division_id` when the conference belongs to a division), when the team belongs to one |
| `division_id` | integer | Division ID, when the team belongs to one |
| `division` | object | Division details (`division_id`, `sport_id`, `name`), when the team belongs to one |

## Market Object

Each market represents a type of bet (moneyline, spread, total, player prop, etc.). Markets are nested inside events.

| Field | Type | Description |
| - | - | - |
| `id` | integer | Instance identifier for this market on this event |
| `market_id` | integer | Canonical market type ID. See [Market IDs](https://docs.therundown.io/reference/markets.md). |
| `period_id` | integer | Period this market applies to. `0` = full game. See [Period IDs](https://docs.therundown.io/reference/periods.md). |
| `name` | string | Display name (e.g., "Moneyline", "Total Over/Under") |
| `market_description` | string | Human-readable description |
| `participants` | array | Array of [Participant objects](#participant-object) |

## Participant Object

Participants are the entities you can bet on within a market — teams, players, or result types (Over/Under).

| Field | Type | Description |
| - | - | - |
| `id` | integer | Participant identifier (team ID, player ID, or `0`/`1` for result types) |
| `type` | string | `TYPE_TEAM`, `TYPE_PLAYER`, or `TYPE_RESULT` |
| `name` | string | Display name (e.g., "Cleveland Cavaliers", "Donovan Mitchell", "Over") |
| `lines` | array | Array of [Line objects](#line-object) |

> [!NOTE]
>
> **`id` is the stable, joinable identifier — join on `id`, not `name`.** What `id` points to depends on `type`:
>
> * **`TYPE_TEAM`** — `id` is the normalized team ID. It is stable across seasons and endpoints, and matches `event.teams[].team_id`. Fetch the full team at `GET /api/v2/teams/{team_id}`.
> * **`TYPE_PLAYER`** — `id` is the player ID. Fetch the full player (team, names, position) at `GET /api/v2/players/{player_id}`.
> * **`TYPE_RESULT`** — `id` is a small outcome index (e.g. `0`/`1` for Over/Under) and is **not** a team or player resource key.
>
> Because every distinct team and player has a distinct `id`, joining on `id` resolves shared-name collisions that joining on `name` cannot. To look up an `id` from a name once, use the roster at `GET /api/v2/teams/{team_id}/players` or the team list at `GET /api/v2/sports/{sportID}/teams`.

## Line Object

A line represents a specific betting line for a participant. For spreads and totals, the `value` contains the line number. An empty value, such as an unlabelled moneyline, is omitted from the response.

| Field | Type | Description |
| - | - | - |
| `id` | string | 32-character hex identifier for this line |
| `value` | string | Optional line value: `"-3.5"` for spread or `"224.5"` for total. Omitted when empty. |
| `prices` | object | Map of affiliate ID → [Price object](#price-object). Keyed by sportsbook. |

> [!NOTE]
>
> `line_value_is_participant` tells you where the meaningful selection detail lives. When it is `true`, the participant carries the selection and the line `value` may be a placeholder or label. When it is `false`, display the line `value` when present; it may be a number, threshold, method, round, or other outcome qualifier.

## Price Object

A price is the odds offered by a single sportsbook for a specific line.

| Field | Type | Description |
| - | - | - |
| `id` | string | Numeric string identifier for this price |
| `price` | number | American odds (e.g., `-110`, `+150`). A value of `0.0001` means the line is off the board. See [Sentinel Values](https://docs.therundown.io/reference/sentinel-values.md). |
| `is_main_line` | boolean | Whether this affiliate's quote is flagged as a main line. Use `main_line=true` query param to filter to main lines only. |
| `updated_at` | string | ISO 8601 timestamp of the last price update |
| `source_id` | string | The sportsbook's own identifier for this price/selection, when available (omitted otherwise). For Polymarket it encodes the event slug, Gamma market ID, and CLOB token ID — see [Source identifiers](https://docs.therundown.io/reference/sportsbooks.md#source-identifiers-mapping-to-a-book%E2%80%99s-own-data). |

Fields that appear in delta/history responses:

| Field | Type | Description |
| - | - | - |
| `price_delta` | number | Difference from the previous price (present in some delta responses) |
| `closed_at` | string | Optional ISO 8601 timestamp when a closing time was recorded; omitted when none is recorded. |

For a full current price object, an omitted `closed_at` means open; clear any previously stored closure timestamp when replacing that object. For historical rows and chart points, omission only means that row has no closing timestamp and does not establish the line's current state. Chart responses use the optional `c` field for the same historical closing-time semantics.

Fields present on selected affiliates:

| Field | Type | Description |
| - | - | - |
| `liquidity_usd` | number | USD reading for this price. On Kalshi (affiliate 25) and Polymarket (affiliate 26) this is approximate resting-order-book depth. On Pinnacle (affiliate 3) this is the book's max stake. Novig (affiliate 30) and Polymarket US (affiliate 31) prices also carry a reading. How each venue computes it, and how often it refreshes, differs. See the note below. |
| `deep_link` | string | Link to this exact selection on the sportsbook, on books that support it (for example BetMGM and Kalshi). Omitted when no exact link is available. |

> [!NOTE]
>
> `liquidity_usd` is **omitted** entirely, never `null` and never a fabricated `0`, when a current reading is not available. Treat a missing field as "unknown," not as zero. See [What is `liquidity_usd` on a price object?](https://docs.therundown.io/faq) in the FAQ for what the number means on each affiliate and why it is not on every price.

## Traversing the Data

Market participants are ordered by type and ID, not by home or away side. Find the market by `market_id` and `period_id`, then match a team participant by `type` and its team ID. A filtered or missing market can also change the positions in `markets`.

This helper returns the raw price object, or `None` when the requested market, team, line or affiliate quote is absent. Use `None` for an unlabelled line and the exact returned `value` string for a spread, including its sign. The examples use full-game period `0`.

```python theme={null}
def team_quote(event, market_id, team_id, affiliate_id, line_value=None, period_id=0):
    for market in event["markets"]:
        if market["market_id"] != market_id or market["period_id"] != period_id:
            continue
        for participant in market["participants"]:
            if participant["type"] != "TYPE_TEAM" or participant["id"] != team_id:
                continue
            for line in participant["lines"]:
                value = line.get("value")
                if value == "":
                    value = None
                if value == line_value:
                    return line["prices"].get(str(affiliate_id))
    return None
```

### Reading a moneyline price

Given one returned `event`, select its away team and use the helper above to read that team's DraftKings (`19`) moneyline (`1`):

```python theme={null}
away_team = next(team for team in event["teams"] if team["is_away"])
price_object = team_quote(event, 1, away_team["team_id"], 19)
if price_object is not None:
    print(price_object["price"])
```

Reading a price does not establish its current availability. Apply the `closed_at` rule above before using a quote as available.

### Reading a spread value and price

Using the same helper, request the away team's spread (`2`) at a specific line. `"+3"` is an example; choose a value present in your response.

```python theme={null}
spread_value = "+3"
away_team = next(team for team in event["teams"] if team["is_away"])
price_object = team_quote(event, 2, away_team["team_id"], 19, spread_value)
if price_object is not None:
    print(spread_value, price_object["price"])
```

### Iterating all prices for an event

```python theme={null}
for market in event["markets"]:
    for participant in market["participants"]:
        for line in participant["lines"]:
            for affiliate_id, price_obj in line["prices"].items():
                print(f"{market['name']} | {participant['name']} | "
                      f"{line['value']} | {affiliate_id}: {price_obj['price']}")
```

## Delta Responses

Delta endpoints return a different shape. Instead of the nested event → market → participant → line → price hierarchy, they return **flat change records**:

| Field | Description |
| - | - |
| `event_id` | Which event changed |
| `market_id` | Which market |
| `participant_id` | Which participant |
| `affiliate_id` | Which sportsbook |
| `line` | Line value |
| `price` | New price |
| `previous_price` | Previous price (empty string if new) |
| `change_type` | `"new"`, `"price_change"`, or `"line_change"` |

Use the `event_id`, `market_id`, `participant_id`, and `affiliate_id` to locate the correct entry in your local cache and replace the price. See the [Efficient Polling guide](https://docs.therundown.io/guides/efficient-polling.md) for the full update pattern.


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