The Rundown V2 Events API
Events with market-based odds (V2)
Documentation
Documentation
https://docs.therundown.io/introduction
Authentication
https://docs.therundown.io/authentication
Events with market-based odds (V2)
openapi: 3.0.3
info:
title: TheRundown Sports V1 Delta V2 Events API
version: 2.0.0
description: 'Real-time and historical sports betting data, odds, lines, and statistics across major North American and international sports leagues.
## Authentication
All endpoints (except `/sports` and `/affiliates`) require authentication. Pass your API key using one of:
- **Query parameter**: `?key=YOUR_API_KEY`
- **Header**: `X-Therundown-Key: YOUR_API_KEY`
## Off-the-Board Sentinel Value
The value **0.0001** indicates a line is "off the board" — the sportsbook has temporarily removed pricing (e.g., pending injury news). This is NOT an error. Display as "Off Board" or "N/A" in your UI.
## Rate Limiting
Requests are rate-limited per API key tier. Check response headers for current limits.
## Data Updates
- Live odds update in real-time during games
- Use delta endpoints for efficient polling of changes
- WebSocket connections available for streaming updates
## V1 vs V2
V2 endpoints use market-based data structures (market_id, participants, line prices). V1 endpoints use legacy line-based structures (moneyline, spread, total objects). V2 is recommended for new integrations.
'
contact:
name: TheRundown API Support
url: https://therundown.io
email: support@therundown.io
termsOfService: https://therundown.io/terms
servers:
- url: https://therundown.io
description: Production
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
tags:
- name: V2 Events
description: Events with market-based odds (V2)
paths:
/api/v2/sports/{sportID}/events/{date}:
get:
operationId: v2GetEventsBySportAndDate
tags:
- V2 Events
summary: Get events with markets for a sport and date
description: 'Returns events with full market/odds data for the specified sport and date. This is the primary endpoint for building odds screens.
The response includes `meta.delta_last_id` which serves as the bootstrap cursor for the `/api/v2/markets/delta` polling endpoint.
'
parameters:
- $ref: '#/components/parameters/SportIDPath'
- name: date
in: path
required: true
schema:
type: string
format: date
example: '2026-01-15'
- $ref: '#/components/parameters/OffsetQuery'
- $ref: '#/components/parameters/MarketIDsQuery'
- $ref: '#/components/parameters/ParticipantIDsQuery'
- $ref: '#/components/parameters/ParticipantTypeQuery'
- $ref: '#/components/parameters/AffiliateIDsQuery'
- $ref: '#/components/parameters/MainLineQuery'
- name: hide_no_markets
in: query
schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
description: Hide events with no market data
- name: exclude_status
in: query
schema:
type: string
description: Comma-separated event status strings to exclude
responses:
'200':
description: Events with markets
content:
application/json:
schema:
$ref: '#/components/schemas/EventsV2Response'
example:
meta:
delta_last_id: 11ef-abcd-1234-5678-9012-abcdef123456
events:
- event_id: 816efd1e5767d7133b5bc70c77173a18
sport_id: 4
event_uuid: 11f1-197d-e93ea800-8c2a-ef6a554ca62d
event_date: '2026-01-15T00:00:00Z'
score:
event_status: STATUS_SCHEDULED
score_away: 0
score_home: 0
game_period: 0
game_clock: 0
teams:
- team_id: 145
name: Los Angeles
mascot: Lakers
abbreviation: LAL
record: 38-18
is_away: true
is_home: false
- team_id: 153
name: Boston
mascot: Celtics
abbreviation: BOS
record: 42-14
is_away: false
is_home: true
schedule:
event_name: Los Angeles Lakers at Boston Celtics
season_type: Regular Season
season_year: 2026
markets:
- market_id: 1
period_id: 0
name: moneyline
participants:
- id: 145
type: TYPE_TEAM
name: Los Angeles Lakers
lines:
- value: ''
prices:
'19':
price: 150
is_main_line: true
updated_at: '2026-01-14T22:30:00Z'
'23':
price: 155
is_main_line: true
updated_at: '2026-01-14T22:28:00Z'
- id: 153
type: TYPE_TEAM
name: Boston Celtics
lines:
- value: ''
prices:
'19':
price: -180
is_main_line: true
updated_at: '2026-01-14T22:30:00Z'
'23':
price: -185
is_main_line: true
updated_at: '2026-01-14T22:28:00Z'
- market_id: 2
period_id: 0
name: handicap
participants:
- id: 145
type: TYPE_TEAM
name: Los Angeles Lakers
lines:
- value: '4.5'
prices:
'19':
price: -110
is_main_line: true
updated_at: '2026-01-14T22:30:00Z'
'23':
price: -108
is_main_line: true
updated_at: '2026-01-14T22:28:00Z'
- id: 153
type: TYPE_TEAM
name: Boston Celtics
lines:
- value: '-4.5'
prices:
'19':
price: -110
is_main_line: true
updated_at: '2026-01-14T22:30:00Z'
'23':
price: -112
is_main_line: true
updated_at: '2026-01-14T22:28:00Z'
- market_id: 3
period_id: 0
name: totals
participants:
- id: 1001
type: TYPE_RESULT
name: Over
lines:
- value: '224.5'
prices:
'19':
price: -110
is_main_line: true
updated_at: '2026-01-14T22:30:00Z'
- id: 1002
type: TYPE_RESULT
name: Under
lines:
- value: '224.5'
prices:
'19':
price: -110
is_main_line: true
updated_at: '2026-01-14T22:30:00Z'
/api/v2/sports/{sportID}/openers/{date}:
get:
operationId: v2GetOpenersBySportAndDate
tags:
- V2 Events
summary: Get opening lines for a sport and date
description: Returns events with the earliest recorded market prices (opening lines).
parameters:
- $ref: '#/components/parameters/SportIDPath'
- name: date
in: path
required: true
schema:
type: string
format: date
- $ref: '#/components/parameters/OffsetQuery'
- $ref: '#/components/parameters/MarketIDsQuery'
- $ref: '#/components/parameters/AffiliateIDsQuery'
- $ref: '#/components/parameters/MainLineQuery'
- name: hide_closed
in: query
schema:
type: string
enum:
- 'true'
- 'false'
description: Hide closed lines
responses:
'200':
description: Events with opening market prices
content:
application/json:
schema:
$ref: '#/components/schemas/EventsV2Response'
example:
meta: null
events:
- event_id: 09bfa53f8484a63e584398545c035932
sport_id: 4
event_date: '2026-02-12T00:00:00Z'
teams:
- team_id: 11
name: Atlanta
mascot: Hawks
abbreviation: ATL
is_away: true
is_home: false
- team_id: 12
name: Charlotte
mascot: Hornets
abbreviation: CHA
is_away: false
is_home: true
markets:
- market_id: 1
name: moneyline
participants:
- name: Atlanta Hawks
type: TYPE_TEAM
lines:
- value: '0'
prices:
'19':
price: -105
is_main_line: true
updated_at: '2026-02-11T22:00:00Z'
/api/v2/events/{eventID}:
get:
operationId: v2GetEventByID
tags:
- V2 Events
summary: Get a single event with markets
parameters:
- $ref: '#/components/parameters/EventIDPath'
- $ref: '#/components/parameters/MarketIDsQuery'
- $ref: '#/components/parameters/ParticipantIDsQuery'
- $ref: '#/components/parameters/ParticipantTypeQuery'
- $ref: '#/components/parameters/AffiliateIDsQuery'
- $ref: '#/components/parameters/MainLineQuery'
responses:
'200':
description: Event with markets
content:
application/json:
schema:
$ref: '#/components/schemas/EventsV2Response'
example:
meta: null
events:
- event_id: 09bfa53f8484a63e584398545c035932
sport_id: 4
event_date: '2026-02-12T00:00:00Z'
rotation_number_away: 529
rotation_number_home: 530
score:
event_status: STATUS_FINAL
score_away: 107
score_home: 110
score_away_by_period:
- 27
- 22
- 26
- 32
score_home_by_period:
- 35
- 23
- 31
- 21
venue_name: Spectrum Center
venue_location: Charlotte, NC
broadcast: FanDuel SN SE
event_status_detail: Final
teams:
- team_id: 11
name: Atlanta
mascot: Hawks
abbreviation: ATL
record: 26-30
is_away: true
is_home: false
- team_id: 12
name: Charlotte
mascot: Hornets
abbreviation: CHA
record: 26-29
is_away: false
is_home: true
schedule:
league_name: National Basketball Association
season_type: Regular Season
season_year: 2026
markets:
- id: 2518418
market_id: 1
name: moneyline
participants:
- name: Atlanta Hawks
type: TYPE_TEAM
lines:
- value: '0'
prices:
'19':
price: -105
is_main_line: true
updated_at: '2026-02-11T22:00:00Z'
- id: 2518419
market_id: 2
name: handicap
participants:
- name: Atlanta Hawks
type: TYPE_TEAM
lines:
- value: '4.5'
prices:
'19':
price: -110
is_main_line: true
updated_at: '2026-02-11T22:00:00Z'
- id: 2518420
market_id: 3
name: totals
participants:
- name: Over
type: TYPE_RESULT
lines:
- value: '235.5'
prices:
'19':
price: -110
is_main_line: true
updated_at: '2026-02-12T00:10:43Z'
'404':
description: Event not found
/api/v2/events/{eventID}/openers:
get:
operationId: v2GetEventOpeners
tags:
- V2 Events
summary: Get opening prices for an event
parameters:
- $ref: '#/components/parameters/EventIDPath'
- $ref: '#/components/parameters/MarketIDsQuery'
- $ref: '#/components/parameters/AffiliateIDsQuery'
- $ref: '#/components/parameters/MainLineQuery'
- name: hide_closed
in: query
schema:
type: string
enum:
- 'true'
- 'false'
responses:
'200':
description: Event with opening prices
content:
application/json:
schema:
$ref: '#/components/schemas/EventsV2Response'
example:
meta: null
events:
- event_id: 09bfa53f8484a63e584398545c035932
sport_id: 4
event_date: '2026-02-12T00:00:00Z'
teams:
- team_id: 11
name: Atlanta
mascot: Hawks
abbreviation: ATL
is_away: true
is_home: false
- team_id: 12
name: Charlotte
mascot: Hornets
abbreviation: CHA
is_away: false
is_home: true
markets:
- market_id: 1
name: moneyline
participants:
- name: Atlanta Hawks
type: TYPE_TEAM
lines:
- value: '0'
prices:
'19':
price: -120
is_main_line: true
updated_at: '2026-02-10T15:00:00Z'
/api/v2/events/{eventID}/best-line:
get:
operationId: v2GetBestLineByEvent
tags:
- V2 Events
summary: Get best available line for an event
description: Returns the best moneyline, spread, and total across all sportsbooks.
parameters:
- $ref: '#/components/parameters/EventIDPath'
- name: period
in: query
schema:
type: string
default: period_full_game
enum:
- period_full_game
- period_first_half
- period_second_half
- period_first_period
- period_second_period
- period_third_period
- period_fourth_period
- period_live_full_game
- period_live_first_half
- period_live_second_half
- period_live_first_period
- period_live_second_period
- period_live_third_period
- period_live_fourth_period
description: Period to get best line for
- $ref: '#/components/parameters/AffiliateIDsQuery'
responses:
'200':
description: Best lines
content:
application/json:
schema:
$ref: '#/components/schemas/BestLineResponse'
example:
event_id: 09bfa53f8484a63e584398545c035932
moneyline:
moneyline_away: 155
moneyline_home: -170
best_affiliate_away:
affiliate_id: 23
affiliate_name: FanDuel
updated_at: '2026-02-12T00:10:00Z'
best_affiliate_home:
affiliate_id: 19
affiliate_name: DraftKings
updated_at: '2026-02-12T00:10:00Z'
spread:
point_spread_away: 4.5
point_spread_home: -4.5
point_spread_away_money: -105
point_spread_home_money: -108
best_affiliate_away:
affiliate_id: 3
affiliate_name: Pinnacle
updated_at: '2026-02-12T00:08:00Z'
best_affiliate_home:
affiliate_id: 23
affiliate_name: FanDuel
updated_at: '2026-02-12T00:10:00Z'
total:
total_over: 224.5
total_under: 224.5
total_over_money: -108
total_under_money: -105
best_affiliate_over:
affiliate_id: 19
affiliate_name: DraftKings
updated_at: '2026-02-12T00:10:00Z'
best_affiliate_under:
affiliate_id: 3
affiliate_name: Pinnacle
updated_at: '2026-02-12T00:08:00Z'
/api/v2/delta:
get:
operationId: v2GetDelta
tags:
- V2 Events
summary: Get event changes since a delta ID
description: 'Returns raw JSON delta payloads for events that changed since `last_id`. Each delta entry is a raw JSON string containing the full event update — the `data` field is a serialized JSON string, not a parsed object.
The response is wrapped in a `meta` object containing the `delta_last_id` cursor for subsequent polling.
'
parameters:
- name: last_id
in: query
required: true
schema:
type: string
minLength: 36
maxLength: 36
description: Delta cursor (36-character UUID). Use `00000000-0000-0000-0000-000000000000` for initial fetch, then pass the `delta_last_id` from the previous response.
- name: sport_id
in: query
schema:
type: integer
description: Filter by sport ID
- $ref: '#/components/parameters/AffiliateIDsQuery'
responses:
'200':
description: Delta updates
content:
application/json:
schema:
$ref: '#/components/schemas/DeltasResponse'
example:
meta:
delta_last_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
deltas:
- data: '{"event_id":"09bfa53f8484a63e584398545c035932","sport_id":4,"event_date":"2026-02-12T00:00:00Z","lines":{...}}'
- data: '{"event_id":"b9c4e2a1f3d5670089ab12cd34ef5678","sport_id":4,"event_date":"2026-02-12T00:00:00Z","lines":{...}}'
components:
schemas:
Pitcher:
type: object
properties:
id:
type: integer
name:
type: string
throws_left_handed:
type: boolean
nullable: true
throws_right_handed:
type: boolean
nullable: true
bats_left_handed:
type: boolean
nullable: true
bats_right_handed:
type: boolean
nullable: true
MarketResponse:
type: object
description: Market with participants and prices for a specific event
properties:
id:
type: integer
format: int64
market_id:
type: integer
example: 1
period_id:
type: integer
name:
type: string
example: Money Line
market_description:
type: string
participants:
type: array
items:
$ref: '#/components/schemas/MarketParticipantResponse'
EventV2:
type: object
properties:
event_id:
type: string
description: Canonical event identifier string used by V2 endpoints, filters, and delta feeds.
example: 816efd1e5767d7133b5bc70c77173a18
event_uuid:
type: string
description: Compatibility identifier retained for older integrations. Do not assume it matches `event_id`.
example: 11f1-197d-e93ea800-8c2a-ef6a554ca62d
sport_id:
type: integer
example: 4
event_date:
type: string
format: date-time
rotation_number_away:
type: integer
rotation_number_home:
type: integer
score:
$ref: '#/components/schemas/Score'
teams:
type: array
items:
$ref: '#/components/schemas/TeamNormalized'
schedule:
$ref: '#/components/schemas/Schedule'
pitcher_away:
$ref: '#/components/schemas/Pitcher'
pitcher_home:
$ref: '#/components/schemas/Pitcher'
markets:
type: array
items:
$ref: '#/components/schemas/MarketResponse'
BestAffiliateInfo:
type: object
properties:
affiliate_id:
type: integer
affiliate_name:
type: string
updated_at:
type: string
format: date-time
BestMoneyline:
type: object
properties:
moneyline_home:
type: number
nullable: true
moneyline_away:
type: number
nullable: true
moneyline_draw:
type: number
nullable: true
best_affiliate_home:
$ref: '#/components/schemas/BestAffiliateInfo'
best_affiliate_away:
$ref: '#/components/schemas/BestAffiliateInfo'
best_affiliate_draw:
$ref: '#/components/schemas/BestAffiliateInfo'
Meta:
type: object
properties:
delta_last_id:
type: string
Score:
type: object
properties:
event_id:
type: string
event_status:
type: string
description: 'Event status. Common values: STATUS_SCHEDULED, STATUS_IN_PROGRESS, STATUS_FINAL, STATUS_POSTPONED, STATUS_CANCELED, STATUS_SUSPENDED, STATUS_DELAYED, STATUS_RAIN_DELAY, STATUS_HALFTIME, STATUS_END_PERIOD, STATUS_END_OF_REGULATION, STATUS_OVERTIME, STATUS_FIRST_HALF, STATUS_SECOND_HALF
'
team_id_away:
type: integer
description: Away team ID. Omitted when zero.
team_id_home:
type: integer
description: Home team ID. Omitted when zero.
score_away:
type: integer
score_home:
type: integer
winner_away:
type: integer
winner_home:
type: integer
score_away_by_period:
type: array
items:
type: integer
score_home_by_period:
type: array
items:
type: integer
venue_name:
type: string
description: Arena or stadium name. May be an empty string when unavailable from the live feed.
venue_location:
type: string
description: City and state. May be an empty string when unavailable from the live feed.
game_clock:
type: integer
display_clock:
type: string
game_period:
type: integer
broadcast:
type: string
event_status_detail:
type: string
updated_at:
type: string
format: date-time
Schedule:
type: object
properties:
season_type:
type: string
example: Regular Season
season_year:
type: integer
example: 2026
conference_competition:
type: boolean
nullable: true
conference_name:
type: string
league_name:
type: string
nullable: true
event_name:
type: string
attendance:
type: string
event_headline:
type: string
week:
type: integer
week_name:
type: string
week_detail:
type: string
BestTotal:
type: object
properties:
total_over:
type: number
nullable: true
total_under:
type: number
nullable: true
total_over_money:
type: number
nullable: true
total_under_money:
type: number
nullable: true
best_affiliate_over:
$ref: '#/components/schemas/BestAffiliateInfo'
best_affiliate_under:
$ref: '#/components/schemas/BestAffiliateInfo'
BestLineResponse:
type: object
properties:
event_id:
type: string
moneyline:
$ref: '#/components/schemas/BestMoneyline'
spread:
$ref: '#/components/schemas/BestSpread'
total:
$ref: '#/components/schemas/BestTotal'
periods:
type: object
description: Period-specific best lines keyed by period name
additionalProperties:
type: object
properties:
moneyline:
$ref: '#/components/schemas/BestMoneyline'
spread:
$ref: '#/components/schemas/BestSpread'
total:
$ref: '#/components/schemas/BestTotal'
BestSpread:
type: object
properties:
point_spread_home:
type: number
nullable: true
point_spread_away:
type: number
nullable: true
point_spread_home_money:
type: number
nullable: true
point_spread_away_money:
type: number
nullable: true
best_affiliate_home:
$ref: '#/components/schemas/BestAffiliateInfo'
best_affiliate_away:
$ref: '#/components/schemas/BestAffiliateInfo'
TeamNormalized:
type: object
properties:
team_id:
type: integer
name:
type: string
mascot:
type: string
abbreviation:
type: string
record:
type: string
is_home:
type: boolean
is_away:
type: boolean
ranking:
type: integer
nullable: true
conference:
$ref: '#/components/schemas/Conference'
division:
$ref: '#/components/schemas/Division'
EventsV2Response:
type: object
properties:
meta:
$ref: '#/components/schemas/Meta'
events:
type: array
items:
$ref: '#/components/schemas/EventV2'
Conference:
type: object
properties:
conference_id:
type: integer
sport_id:
type: integer
name:
type: string
MarketParticipantResponse:
type: object
properties:
id:
type: integer
description: Participant ID
type:
type: string
enum:
- TYPE_TEAM
- TYPE_PLAYER
- TYPE_RESULT
name:
type: string
example: New England Patriots
lines:
type: array
items:
$ref: '#/components/schemas/MarketLinesResponse'
MarketLinesResponse:
type: object
properties:
id:
type: string
value:
type: string
description: Line value (numeric for spreads/totals, participant name if `line_value_is_participant` is true)
selection:
type: string
handicap:
type: string
prices:
type: object
description: Prices keyed by affiliate ID
additionalProperties:
$ref: '#/components/schemas/MarketLinePriceResponse'
MarketLinePriceResponse:
type: object
properties:
id:
type: string
price:
type: number
description: American odds price. Value of 0.0001 means "off the board".
example: -110
price_delta:
type: number
nullable: true
description: Change from previous price
is_main_line:
type: boolean
description: Whether this is the primary/main line
updated_at:
type: string
format: date-time
closed_at:
type: string
format: date-time
nullable: true
DeltasResponse:
type: object
properties:
meta:
$ref: '#/components/schemas/Meta'
deltas:
type: array
items:
type: object
properties:
data:
type: string
description: Raw JSON string of the delta payload
Division:
type: object
properties:
division_id:
type: integer
conference_id:
type: integer
sport_id:
type: integer
name:
type: string
parameters:
EventIDPath:
name: eventID
in: path
required: true
schema:
type: string
description: Canonical V2 event ID from the `event_id` field returned by event endpoints
AffiliateIDsQuery:
name: affiliate_ids
in: query
schema:
type: string
description: Comma-separated sportsbook/affiliate IDs to filter. Common values include DraftKings (19), FanDuel (23), BetMGM (22), Bovada (2), Pinnacle (3).
MarketIDsQuery:
name: market_ids
in: query
schema:
type: string
default: 1,2,3
description: 'Comma-separated market IDs. Defaults to `1,2,3` (Moneyline, Spread, Total).
**Limit: 12 market IDs per request.** IDs beyond the 12th are silently ignored.
Common IDs: 1=Moneyline, 2=Spread, 3=Total, 29=Player Points, 35=Player Rebounds, 38=Three Pointers, 39=Player Assists, 93=Player PRA, 94=Team Totals.
Live variants: 41=Live ML, 42=Live Spread, 43=Live Total.
If you need more than 12 markets, make multiple requests.
'
MainLineQuery:
name: main_line
in: query
schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
description: Only return main lines (primary odds, not alternates)
ParticipantIDsQuery:
name: participant_ids
in: query
schema:
type: string
description: Comma-separated participant IDs to filter (max 99)
ParticipantTypeQuery:
name: participant_type
in: query
schema:
type: string
enum:
- TYPE_TEAM
- TYPE_PLAYER
- TYPE_RESULT
description: Filter participants by type
OffsetQuery:
name: offset
in: query
schema:
type: integer
default: 0
example: 300
description: UTC offset in **minutes** for the date boundary. Use `300` for US Central, `240` for Eastern, `360` for Mountain, `420` for Pacific. Without this, the API day
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/therundown/refs/heads/main/openapi/therundown-v2-events-api-openapi.yml