Skip to main content
TheRundown provides WebSocket endpoints for real-time data delivery. Instead of polling REST endpoints, open a persistent connection and receive updates as they happen. WebSocket traffic does not increment the HTTP request counter, but pushed messages and snapshots are still metered as data points.
WebSocket access requires a real-time API tier (Ultra and above). If your key does not have WebSocket access, use the market delta endpoint for ongoing updates.

Available WebSocket Endpoints

This guide covers the V2 Markets stream. For the multiplexed endpoint — connecting, subscribing to channels, and streaming play-by-play or live game stats — see the Multiplexed WebSocket guide and the WebSocket reference.

V2 Markets WebSocket

The primary WebSocket for real-time odds data. Delivers individual price updates in a flat format — each message contains one price change for one participant, market, and sportsbook.

Connection

Connect to wss://therundown.io/api/v2/ws/markets from a server-side client and send X-TheRundown-Key: $THERUNDOWN_API_KEY in the upgrade request. Native browser WebSocket clients cannot set custom headers; have the browser connect to your authenticated backend relay instead.

Filter Parameters

All filters are optional. Without filters, you receive updates for all sports and markets.

Example: Filtered Connection

Message Format

Each message is a JSON object with meta (message metadata) and data (the price update). Each message represents a single price change — not a full market snapshot.

Code Examples

For Node.js, install ws with npm install ws. The Python examples use websockets>=14, where additional_headers adds request headers to the handshake.

V1 WebSocket (Legacy)

The V1 WebSocket delivers line updates with meta.type identifying the market type (e.g., "moneyline", "spread", "total"). The data object contains market-specific fields with _delta suffixes showing the change from the previous value. Use this only if your application has not migrated to V2.

Connection

Use V1 only for an existing legacy integration. New streaming integrations should use V2, which authenticates the WebSocket upgrade with the request header above.

Filter Parameters

Example Message

Heartbeat Handling

All WebSocket endpoints send heartbeat messages every 15 seconds to keep the connection alive. Your client must handle these to avoid treating them as data updates.
Heartbeats arrive every 15 seconds. If you do not receive one within 60 seconds (i.e., four missed heartbeats), the connection is likely stale. Close and reconnect.

Heartbeat Handler Pattern

Reconnection Best Practices

WebSocket connections can drop due to network issues, server maintenance, or client-side timeouts. Always implement automatic reconnection.
  1. Exponential backoff — start at 1 second, double on each failure, cap at 30 seconds.
  2. Add jitter — randomize the delay slightly to avoid thundering herd reconnections.
  3. Reset backoff on success — once a connection is established and receives data, reset the delay to 1 second.
  4. Refetch REST state after reconnect — you may have missed updates during the disconnection. Fetch the latest state from the REST API to ensure consistency.

Tips for Production

Always specify sport_ids and market_ids in your WebSocket connection. Receiving updates for all sports and markets generates significant traffic that your client may not need.
Do not block the WebSocket message handler with slow operations (database writes, API calls). Queue updates and process them in a separate thread or task.
After a reconnect, fetch the latest state from the REST API to fill any gaps. WebSocket updates are incremental — if you miss one, your state may be stale.
Track heartbeat intervals and reconnection frequency. Alert if the connection drops repeatedly, which may indicate a network issue or an invalid API key.

Next Steps

Multiplexed WebSocket

Markets, scores, plays, game stats, and live game state over one connection

Building an Odds Screen

Use WebSocket data in a real-time UI

Getting Live Odds

REST API for initial data load

Rate Limits

WebSocket does not count against REST limits

V1 to V2 Migration

Migrate from V1 WebSocket to V2