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 is enabled on real-time API tiers by default. If your key does not have WebSocket access, use the market delta endpoint for ongoing updates.

Available WebSocket Endpoints

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

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

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

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

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