Skip to main content
For new integrations, use the V2 WebSocket endpoints: /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:
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.

Example Connection URLs

These URLs contain only subscription filters. Send authentication in the handshake header, never in the URL.
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:
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'.

V1 vs V2 WebSocket Comparison

Use the dedicated V2 Markets WebSocket when you need prices only. Use the multiplexed endpoint when you need multiple feeds or live scores, plays, or box-score changes on one connection.