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
| Endpoint | URL | Description |
|---|---|---|
| V2 Markets | wss://therundown.io/api/v2/ws/markets | Real-time market/price updates for all V2 data |
| V1 (Legacy) | wss://therundown.io/api/v1/ws | Legacy format line updates |
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.| Parameter | Type | Description |
|---|---|---|
key | string | Required. Your API key |
sport_ids | string | Comma-separated sport IDs (e.g., 2,4,6) |
market_ids | string | Comma-separated market IDs (e.g., 1,2,3) |
event_ids | string | Comma-separated event IDs for specific games |
affiliate_ids | string | Comma-separated sportsbook IDs |
Example: Filtered Connection
Message Format
Each message is a JSON object withmeta (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 withmeta.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
| Parameter | Type | Description |
|---|---|---|
key | string | Required. Your API key |
sport_ids | string | Comma-separated sport IDs |
affiliate_ids | string | Comma-separated sportsbook IDs |
event_ids | string | Comma-separated event IDs |
date | string | Date filter (e.g., 2026-02-12) |
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.Heartbeat Handler Pattern
Reconnection Best Practices
WebSocket connections can drop due to network issues, server maintenance, or client-side timeouts. Always implement automatic reconnection.Recommended Strategy
- Exponential backoff — start at 1 second, double on each failure, cap at 30 seconds.
- Add jitter — randomize the delay slightly to avoid thundering herd reconnections.
- Reset backoff on success — once a connection is established and receives data, reset the delay to 1 second.
- 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
Filter aggressively to reduce traffic
Filter aggressively to reduce traffic
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.Process messages asynchronously
Process messages asynchronously
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.
Use the REST API as source of truth after reconnection
Use the REST API as source of truth after reconnection
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.
Monitor connection health
Monitor connection health
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