Documentation
Documentation
https://docs.therundown.io/introduction
Authentication
https://docs.therundown.io/authentication
OpenAPI Specification
openapi: 3.0.3
info:
title: TheRundown Sports V1 Delta V2 Stats 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 Stats
description: Team and player statistics (V2)
paths:
/api/v2/events/{eventID}/stats:
get:
operationId: v2GetStatsByEvent
tags:
- V2 Stats
summary: Get team game stats for an event
parameters:
- $ref: '#/components/parameters/EventIDPath'
- name: stats_ids
in: query
schema:
type: string
description: Comma-separated stat IDs (max 12)
- name: team_id
in: query
schema:
type: integer
description: Filter by team ID
responses:
'200':
description: Team game stats
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TeamGameStatResponse'
example:
- team:
team_id: 11
name: Atlanta Hawks
mascot: Hawks
abbreviation: ATL
meta:
complete: true
stats:
- team_id: 11
stat_id: 1242
stat:
id: 1242
name: avgRebounds
display_name: Rebounds Per Game
abbreviation: REB
sport_id: 4
event_id: 5a0c9d5d8d3e2c0001a1b2c3
value: '42'
- team_id: 11
stat_id: 1243
stat:
id: 1243
name: assistTurnoverRatio
display_name: Assist To Turnover Ratio
abbreviation: AST/TO
sport_id: 4
event_id: 5a0c9d5d8d3e2c0001a1b2c3
value: '2.26'
/api/v2/events/{eventID}/players/stats:
get:
operationId: v2GetPlayerStatsByEvent
tags:
- V2 Stats
summary: Get player game stats for an event
parameters:
- $ref: '#/components/parameters/EventIDPath'
- name: stats_ids
in: query
schema:
type: string
description: Comma-separated stat IDs (max 12)
- name: player_ids
in: query
schema:
type: string
description: Comma-separated player IDs (max 6)
responses:
'200':
description: Player game stats
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerGameStatResponse'
example:
- player:
id: 16627
sport_id: 4
team_id: 11
first_name: Trae
last_name: Young
display_name: Trae Young
jersey: '11'
position: Guard
position_abbreviation: G
meta:
complete: true
stats:
- stat:
id: 1288
name: points
display_name: Points
abbreviation: PTS
sport_id: 4
value: '28'
- stat:
id: 1289
name: assists
display_name: Assists
abbreviation: AST
sport_id: 4
value: '11'
/api/v2/stats:
get:
operationId: v2GetAllStats
tags:
- V2 Stats
summary: List all stat definitions
parameters:
- name: id
in: query
schema:
type: integer
description: Filter by stat ID
- name: sport_id
in: query
schema:
type: integer
description: Filter by sport ID
responses:
'200':
description: Stat definitions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StatDefinition'
example:
- id: 1
name: completionPct
display_name: Completion Percentage
abbreviation: CMP%
description: The percentage of completed passes.
sport_id: 2
- id: 2
name: completions
display_name: Completions
abbreviation: CMP
description: The times a player completes a pass to another player.
sport_id: 2
- id: 1242
name: avgRebounds
display_name: Rebounds Per Game
abbreviation: REB
description: The average rebounds per game.
sport_id: 4
components:
schemas:
PlayerNormalized:
type: object
properties:
id:
type: integer
sport_id:
type: integer
team_id:
type: integer
updated_at:
type: string
format: date-time
nullable: true
first_name:
type: string
last_name:
type: string
display_name:
type: string
weight:
type: number
height:
type: number
display_weight:
type: string
display_height:
type: string
age:
type: integer
date_of_birth:
type: string
slug:
type: string
jersey:
type: string
position:
type: string
position_abbreviation:
type: string
debut_year:
type: integer
birth_place_city:
type: string
birth_place_country:
type: string
experience_years:
type: integer
active:
type: boolean
status:
type: string
bats:
type: string
description: MLB only — batting side
throws:
type: string
description: MLB only — throwing arm
TeamGameStats:
type: object
properties:
team_id:
type: integer
nullable: true
team:
$ref: '#/components/schemas/TeamNormalized'
stat_id:
type: integer
nullable: true
stat:
$ref: '#/components/schemas/StatDefinition'
event_id:
type: string
value:
type: string
StatDefinition:
type: object
properties:
id:
type: integer
nullable: true
name:
type: string
category:
type: string
display_name:
type: string
abbreviation:
type: string
description:
type: string
sport_id:
type: integer
Conference:
type: object
properties:
conference_id:
type: integer
sport_id:
type: integer
name:
type: string
StatsMeta:
type: object
properties:
complete:
type: boolean
TeamGameStatResponse:
type: object
properties:
team:
$ref: '#/components/schemas/TeamNormalized'
meta:
$ref: '#/components/schemas/StatsMeta'
stats:
type: array
items:
$ref: '#/components/schemas/TeamGameStats'
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'
PlayerGameStats:
type: object
properties:
event_id:
type: string
player_id:
type: integer
nullable: true
player:
$ref: '#/components/schemas/PlayerNormalized'
stat_id:
type: integer
nullable: true
stat:
$ref: '#/components/schemas/StatDefinition'
value:
type: string
updated_at:
type: string
format: date-time
nullable: true
Division:
type: object
properties:
division_id:
type: integer
conference_id:
type: integer
sport_id:
type: integer
name:
type: string
PlayerGameStatResponse:
type: object
properties:
player:
$ref: '#/components/schemas/PlayerNormalized'
meta:
$ref: '#/components/schemas/StatsMeta'
stats:
type: array
items:
$ref: '#/components/schemas/PlayerGameStats'
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
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: key
description: API key as query parameter
ApiKeyHeader:
type: apiKey
in: header
name: X-Therundown-Key
description: API key as request header