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

# WebSocket (V1)

> V1 legacy WebSocket for real-time event and line updates: filters, heartbeat, message queue, and how it compares with V2

> [!WARNING]
>
> For new integrations, use the [V2 WebSocket endpoints](https://docs.therundown.io/api-reference/v2/websocket.md): `/api/v2/ws/markets` for a dedicated market-price feed, or multiplexed `/api/v2/ws` for `markets`, `scores`, `plays`, `stats`, `futures`, and `live` subscriptions. The V1 WebSocket is maintained for backward compatibility.

## Overview

The V1 WebSocket streams event updates and V2 market price deltas over a single connection. It combines both V1 event changes and V2 market data into one feed.

***

## Endpoint

### `GET /api/v1/ws`

Connect to:

```
wss://therundown.io/api/v1/ws
```

Authenticate the WebSocket handshake with the `X-TheRundown-Key` header. V1 WebSocket access requires an Ultra or higher plan.

### Filter Parameters

All filters are optional. If none are specified, you receive all messages.

| Parameter | Description |
| - | - |
| `affiliate_ids` | Comma-separated sportsbook IDs (e.g., `19,23`) |
| `sport_ids` | Comma-separated sport IDs (e.g., `4,6`). Applies to V1 messages only. |
| `event_ids` | Comma-separated event IDs |
| `date` | Date filter in `YYYY-MM-DD` format. Applies to V1 messages only. |

### Example Connection URLs

These URLs contain only subscription filters. Send authentication in the handshake header, never in the URL.

```text theme={null}
# All updates
wss://therundown.io/api/v1/ws

# NBA updates only
wss://therundown.io/api/v1/ws?sport_ids=4

# Specific events
wss://therundown.io/api/v1/ws?event_ids=EVENT_ID_1,EVENT_ID_2

# DraftKings and FanDuel on a given date
wss://therundown.io/api/v1/ws?affiliate_ids=19,23&date=2026-02-12
```

> [!NOTE]
>
> Native browser WebSocket clients cannot set custom handshake headers. Have the browser connect to your own authenticated backend relay, which keeps `THERUNDOWN_API_KEY` on the server. Do not put the key in a browser bundle or URL.

***

## Heartbeat

The server sends a heartbeat message every **15 seconds**:

```json theme={null}
{
  "meta": {
    "type": "heartbeat"
  },
  "data": {
    "now": "2026-02-12T20:15:00Z"
  }
}
```

Use heartbeats to verify the connection is alive. If no message (including heartbeats) arrives within 30 seconds, assume the connection is dead and reconnect.

***

## Message Queue

Each client has a **1024-message buffer**. If your client cannot process messages fast enough, the server drops the oldest undelivered messages. To minimize the risk of dropped messages:

* Filter to specific sports, events, or affiliates
* Process messages quickly in your handler
* Offload heavy work to a separate thread or queue

***

## Client Example

Run these server-side examples with Node.js 22+ or Python. Install the required client before using it: `npm install ws` or `pip install 'websockets>=14'`.

```javascript Node.js 22+ (server, ESM) theme={null}
import WebSocket from "ws";

const apiKey = process.env.THERUNDOWN_API_KEY;
if (!apiKey) {
  throw new Error("Set THERUNDOWN_API_KEY");
}

const ws = new WebSocket("wss://therundown.io/api/v1/ws?sport_ids=4", {
  headers: { "X-TheRundown-Key": apiKey },
});

ws.on("open", () => {
  console.log("Connected to V1 WebSocket");
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());

  if (msg.meta?.type === "heartbeat") {
    return;
  }

  console.log("Update:", msg.meta?.type, msg.data);
});

ws.on("close", (code) => {
  console.log(`Disconnected: code=${code}`);
  // Reconnect with backoff.
});

ws.on("error", (err) => {
  console.error("WebSocket error:", err);
});
```

```python Python (server) theme={null}
import asyncio
import json
import os
import websockets

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

URL = "wss://therundown.io/api/v1/ws?sport_ids=4"

async def listen():
    async with websockets.connect(
        URL,
        additional_headers={"X-TheRundown-Key": api_key},
    ) as ws:
        print("Connected to V1 WebSocket")
        async for message in ws:
            msg = json.loads(message)

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

            print(f"Update type: {msg['meta'].get('type')}")
            print(f"Data: {json.dumps(msg['data'], indent=2)[:200]}")

asyncio.run(listen())
```

***

## V1 vs V2 WebSocket Comparison

| Feature | V1 (`/api/v1/ws`) | V2 Markets (`/api/v2/ws/markets`) | V2 Multiplexed (`/api/v2/ws`) |
| - | - | - | - |
| Event/score updates | Yes | No | Yes (`scores` or `live`) |
| Market price updates | Yes (mixed) | Yes (dedicated) | Yes (`markets`) |
| Play-by-play | No | No | Yes (`plays` or `live`, Ultra+) |
| Live game-stat deltas | No | No | Yes (`stats` or `live`, Ultra+) |
| `sport_ids` filter | Yes | Yes | Yes |
| `event_ids` filter | Yes | Yes | Yes |
| `market_ids` filter | No | Yes | Markets only |
| `affiliate_ids` filter | Yes | Yes | Markets only |
| `date` filter | Yes | No | Snapshot scope only (not live-delta filtering) |

> [!NOTE]
>
> Use the dedicated V2 Markets WebSocket when you need prices only. Use the [multiplexed endpoint](https://docs.therundown.io/guides/multiplexed-websocket.md) when you need multiple feeds or live scores, plays, or box-score changes on one connection.


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