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

# Delta (V1)

> V1 delta/change feeds for efficient polling of event and line updates

> [!NOTE]
>
> V1 delta endpoints accept the optional `odds_format` query parameter. It defaults to `american`; the delta fields remain in American-point difference units. See [Choose an odds format](https://docs.therundown.io/guides/odds-formats.md) for details.

## Overview

Delta endpoints return only events that have changed since your last request, identified by a cursor (`last_id`). This is dramatically more efficient than re-fetching all events on every poll cycle and keeps you well within your rate limit.

TheRundown provides two V1 delta endpoints:

| Endpoint | Response Format | Description |
| - | - | - |
| `GET /api/v1/delta` | V1 line-based | Returns changed events in V1 format with `lines` / `line_periods` |
| `GET /api/v1/deltaV2` | Per-change entries | Returns the same entries as `/api/v2/delta` (one per changed line or score) via the V1 path |

> [!NOTE]
>
> For new integrations, consider using `GET /api/v2/delta` or `GET /api/v2/markets/delta` instead. These V1 delta endpoints are maintained for backward compatibility.

> [!WARNING]
>
> Delta feeds are not a way to remove a plan's data delay. Use cursor polling only when the API confirms zero-delay access for that key. Delayed or unknown access should repeat narrow snapshots at an interval appropriate to its returned data delay. See [Efficient Polling](https://docs.therundown.io/guides/efficient-polling.md) for the V2 market-delta bootstrap rules.

***

> [!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/delta — Event deltas (V1 format)
>
> Returns events that have changed since the specified cursor, using the V1 line-based response format.
>
> ### Parameters
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `last_id` | query | Yes | 36-character event-delta cursor. This route rejects the all-zero cursor with HTTP 400. Start from the `meta.delta_last_id` of a V1 events response, or from the cursor `/api/v1/deltaV2` returns for `last_id=00000000-0000-0000-0000-000000000000`. Pass the `meta.delta_last_id` from each response for subsequent requests. |
> | `sport_id` | query | No | Filter by sport ID |
> | `affiliate_ids` | query | No | Comma-separated sportsbook IDs |
> | `include` | query | No | Set to `all_periods` for period-specific lines |
>
> ```bash Get a starting cursor theme={null}
> if [ -z "${THERUNDOWN_API_KEY:-}" ]; then
>   echo "Set THERUNDOWN_API_KEY" >&2
>   exit 1
> fi
> # /api/v1/delta rejects the all-zero cursor. deltaV2 returns the current
> # cursor (meta.delta_last_id) with no deltas; use it as last_id below.
> curl --fail-with-body -sS --connect-timeout 5 --max-time 20 \
>   -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
>   "https://therundown.io/api/v1/deltaV2?last_id=00000000-0000-0000-0000-000000000000"
> ```
>
> ```bash Subsequent poll 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/delta?last_id=PREVIOUS_DELTA_LAST_ID&sport_id=4"
> ```
>
> ```bash With all periods and specific books 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/delta?last_id=CURSOR&include=all_periods&affiliate_ids=19,23"
> ```

> [accordion] GET /api/v1/deltaV2 — Event deltas (V2 format via V1 path)
>
> Returns the same per-change entries as `/api/v2/delta`, one per changed line or score, accessed via the V1 path. This is useful while you migrate a V1 polling integration.
>
> ### Parameters
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `last_id` | query | Yes | 36-character event-delta cursor. Use `00000000-0000-0000-0000-000000000000` to get the current cursor with no deltas, then pass the `meta.delta_last_id` from each response. |
> | `sport_id` | query | No | Filter by sport ID |
> | `affiliate_ids` | query | No | Comma-separated sportsbook IDs |
>
> ```bash Bootstrap cursor 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/deltaV2?last_id=00000000-0000-0000-0000-000000000000"
> ```
>
> ```bash Subsequent poll 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/deltaV2?last_id=PREVIOUS_DELTA_LAST_ID&sport_id=4"
> ```

***

## Delta Polling Pattern

The delta pattern works as a cursor-based feed. Here is the recommended approach:

### Step 1: Initial load

Load current state from a V1 events response (for example `GET /api/v1/sports/{sportID}/events/{date}`) and keep its `meta.delta_last_id` as your cursor. `/api/v1/delta` rejects a zeroed-out UUID with HTTP 400. If you only need a cursor, `/api/v1/deltaV2` returns the current one for a zeroed-out `last_id`, with no events.

### Step 2: Poll for changes

On each subsequent poll (e.g., every 3-5 seconds), pass the `meta.delta_last_id` from the previous response. The API returns only events that changed since that cursor.

### Step 3: Update your local state

Apply the changes from each delta response to your local data store. Each delta entry contains the full event object, so you can replace your cached version entirely.

```python theme={null}
import os
import requests
import time
from datetime import date

API_KEY = os.environ.get("THERUNDOWN_API_KEY")
if not API_KEY:
    raise RuntimeError("Set THERUNDOWN_API_KEY")

BASE = "https://therundown.io/api/v1"

# Step 1: Initial load (snapshot + starting cursor)
resp = requests.get(
    f"{BASE}/sports/4/events/{date.today().isoformat()}",
    headers={"X-TheRundown-Key": API_KEY},
    timeout=20,
)
resp.raise_for_status()
snapshot = resp.json()
last_id = snapshot["meta"]["delta_last_id"]
print(f"Initial load: {len(snapshot.get('events') or [])} events")

# Step 2: Poll for changes
while True:
    time.sleep(5)
    resp = requests.get(
        f"{BASE}/delta",
        headers={"X-TheRundown-Key": API_KEY},
        params={"last_id": last_id, "sport_id": 4},
        timeout=20,
    )
    resp.raise_for_status()
    data = resp.json()

    events = data.get("events") or []
    if events:
        print(f"Delta: {len(events)} events changed")
        for event in events:
            # Step 3: Update local state
            # upsert_event(event)
            pass

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

***

## Choosing Between Delta Endpoints

| Need | Recommended Endpoint |
| - | - |
| V1 line-based data (legacy integrations) | `GET /api/v1/delta` |
| V2 market-based data via V1 path (migration) | `GET /api/v1/deltaV2` |
| V2 event deltas (recommended for new builds) | `GET /api/v2/delta` |
| V2 market price deltas (most granular) | `GET /api/v2/markets/delta` |
| Real-time streaming (no polling) | [V2 WebSocket](https://docs.therundown.io/api-reference/v2/websocket.md) |


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