Stats

Overview

The stats endpoints provide statistical data at multiple levels: a reference catalog of all stat definitions, team-level game stats per event, and player-level game stats per event. Season-level stats are available through the Teams endpoints. For supported live games, changed box-score rows also stream over the V2 WebSocket.

Live Game Stats over WebSocket

On Ultra plans and higher, subscribe to the stats channel on the multiplexed endpoint:

{
  "action": "subscribe",
  "id": "game-stats",
  "channel": "stats",
  "params": { "event_ids": ["EVENT_ID"] }
}

For supported live games, team and player changes stream at play latency — typically within a few seconds of the corresponding play-by-play update. Like all live game data (plays included), stats trail the on-field action by roughly 15–20 seconds, in line with the typical broadcast delay. The frames are row-level deltas, not full boxes: each team_stats[].stats or player_stats[].stats entry contains one changed value and its stat dictionary. Keep value as a string and upsert by owner ID plus stat_id. Because stats has no snapshot or replay source, use this sequence on first connect, reconnect (including a buffer_overflow:reconnect_and_catchup close), or a detected gap:

Subscribe and buffer incoming game_stats frames.
Fetch the current team box from GET /api/v2/events/{eventID}/stats and player box from GET /api/v2/events/{eventID}/players/stats.
Replace your local baseline, then merge the buffered deltas in order.
Continue merging live deltas. A zero-row frame with complete: true is the terminal completion marker; mark the cached box complete and treat repeats as idempotent. A zero-row frame without complete: true is an invalidation fallback; refetch both REST resources.

The combined live channel includes the same game_stats frames alongside scores and plays. Each changed nested stat row costs one stats data point; a zero-row completion marker or invalidation fallback costs one. See the WebSocket reference for the full payload, filters, completion and fallback shapes, and recovery rules.

Endpoints

GET /api/v2/stats — List all stat definitions

Returns the catalog of all available stat definitions, including IDs, names, and associated sports. Use this to discover which stats_ids are valid for filtering.

Parameters

Parameter	Type	Required	Description
`id`	query	No	Filter by a specific stat ID
`sport_id`	query	No	Filter by sport ID to see only stats relevant to that sport

curl "https://therundown.io/api/v2/stats?key=YOUR_API_KEY"

curl "https://therundown.io/api/v2/stats?key=YOUR_API_KEY&sport_id=4"

curl "https://therundown.io/api/v2/stats?key=YOUR_API_KEY&id=1"

import requests

resp = requests.get(
    "https://therundown.io/api/v2/stats",
    headers={"X-TheRundown-Key": "YOUR_API_KEY"},
    params={"sport_id": 4}
)
stats = resp.json()
for s in stats:
    print(f"{s['id']}: {s['display_name']}")

const resp = await fetch(
  "https://therundown.io/api/v2/stats?key=YOUR_API_KEY&sport_id=4"
);
const stats = await resp.json();
stats.forEach(s => console.log(`${s.id}: ${s.display_name}`));

Example Response

[
  {
    "id": 1,
    "name": "points",
    "display_name": "Points",
    "abbreviation": "PTS",
    "sport_id": 4,
    "category": "scoring"
  },
  {
    "id": 2,
    "name": "rebounds",
    "display_name": "Rebounds",
    "abbreviation": "REB",
    "sport_id": 4,
    "category": "rebounding"
  },
  {
    "id": 3,
    "name": "assists",
    "display_name": "Assists",
    "abbreviation": "AST",
    "sport_id": 4,
    "category": "playmaking"
  },
  {
    "id": 4,
    "name": "steals",
    "display_name": "Steals",
    "abbreviation": "STL",
    "sport_id": 4,
    "category": "defense"
  },
  {
    "id": 5,
    "name": "blocks",
    "display_name": "Blocks",
    "abbreviation": "BLK",
    "sport_id": 4,
    "category": "defense"
  }
]

GET /api/v2/events/{eventID}/stats — Team game stats

Returns team-level statistics for a specific event (game). Includes box score data like points, rebounds, assists, etc.

Parameters

Parameter	Type	Required	Description
`eventID`	path	Yes	Canonical V2 event ID from the `event_id` field
`stats_ids`	query	No	Comma-separated stat IDs to include (max 12). If omitted, returns all available stats.
`team_id`	query	No	Filter to a specific team

curl "https://therundown.io/api/v2/events/EVENT_ID/stats?key=YOUR_API_KEY"

curl "https://therundown.io/api/v2/events/EVENT_ID/stats?key=YOUR_API_KEY&stats_ids=1,2,3&team_id=42"

import requests

resp = requests.get(
    "https://therundown.io/api/v2/events/EVENT_ID/stats",
    headers={"X-TheRundown-Key": "YOUR_API_KEY"},
    params={"stats_ids": "1,2,3"}
)

for team_stat in resp.json():
    print(f"{team_stat['team']['name']}")
    for stat in team_stat["stats"]:
        print(f"  {stat['stat']['display_name']}: {stat['value']}")

const resp = await fetch(
  "https://therundown.io/api/v2/events/EVENT_ID/stats?key=YOUR_API_KEY&stats_ids=1,2,3"
);
const teamStats = await resp.json();
teamStats.forEach(t => {
  console.log(t.team.name);
  t.stats.forEach(s => console.log(`  ${s.stat.display_name}: ${s.value}`));
});

Example Response

[
  {
    "team": {
      "team_id": 42,
      "name": "Boston Celtics",
      "abbreviation": "BOS",
      "is_away": true,
      "is_home": false
    },
    "meta": { "complete": true, "event_id": "EVENT_ID" },
    "stats": [
      { "team_id": 42, "stat_id": 1, "stat": { "id": 1, "name": "points", "display_name": "Points", "abbreviation": "PTS", "sport_id": 4 }, "event_id": "EVENT_ID", "value": "112" },
      { "team_id": 42, "stat_id": 2, "stat": { "id": 2, "name": "rebounds", "display_name": "Rebounds", "abbreviation": "REB", "sport_id": 4 }, "event_id": "EVENT_ID", "value": "48" }
    ]
  },
  {
    "team": {
      "team_id": 45,
      "name": "Los Angeles Lakers",
      "abbreviation": "LAL",
      "is_away": false,
      "is_home": true
    },
    "meta": { "complete": true, "event_id": "EVENT_ID" },
    "stats": [
      { "team_id": 45, "stat_id": 1, "stat": { "id": 1, "name": "points", "display_name": "Points", "abbreviation": "PTS", "sport_id": 4 }, "event_id": "EVENT_ID", "value": "105" },
      { "team_id": 45, "stat_id": 2, "stat": { "id": 2, "name": "rebounds", "display_name": "Rebounds", "abbreviation": "REB", "sport_id": 4 }, "event_id": "EVENT_ID", "value": "42" }
    ]
  }
]

Stats are only available for events that have started or completed. Requesting stats for a future event returns an empty array. The nested team identity includes canonical is_away and is_home flags.

GET /api/v2/events/{eventID}/players/stats — Player game stats

Returns individual player statistics for a specific event. Includes per-player box score data.

Parameters

Parameter	Type	Required	Description
`eventID`	path	Yes	Canonical V2 event ID from the `event_id` field
`stats_ids`	query	No	Comma-separated stat IDs to include (max 12)
`player_ids`	query	No	Comma-separated player IDs to filter (max 6)

curl "https://therundown.io/api/v2/events/EVENT_ID/players/stats?key=YOUR_API_KEY"

curl "https://therundown.io/api/v2/events/EVENT_ID/players/stats?key=YOUR_API_KEY&player_ids=100,101,102"

curl "https://therundown.io/api/v2/events/EVENT_ID/players/stats?key=YOUR_API_KEY&stats_ids=1,2,3"

import requests

resp = requests.get(
    "https://therundown.io/api/v2/events/EVENT_ID/players/stats",
    headers={"X-TheRundown-Key": "YOUR_API_KEY"},
    params={"stats_ids": "1,2,3"}
)
for p in resp.json():
    print(f"{p['player']['display_name']}")
    for s in p["stats"]:
        print(f"  {s['stat']['display_name']}: {s['value']}")

const resp = await fetch(
  "https://therundown.io/api/v2/events/EVENT_ID/players/stats?key=YOUR_API_KEY&stats_ids=1,2,3"
);
const playerStats = await resp.json();
playerStats.forEach(p => {
  console.log(p.player.display_name);
  p.stats.forEach(s => console.log(`  ${s.stat.display_name}: ${s.value}`));
});

Example Response

[
  {
    "player": {
      "id": 1002,
      "display_name": "Jayson Tatum",
      "position": "SF",
      "team_id": 42
    },
    "meta": { "complete": true, "event_id": "EVENT_ID" },
    "stats": [
      { "stat": { "id": 1, "name": "points", "display_name": "Points", "abbreviation": "PTS", "sport_id": 4 }, "value": "32" },
      { "stat": { "id": 2, "name": "rebounds", "display_name": "Rebounds", "abbreviation": "REB", "sport_id": 4 }, "value": "9" }
    ]
  },
  {
    "player": {
      "id": 1001,
      "display_name": "LeBron James",
      "position": "SF",
      "team_id": 45
    },
    "meta": { "complete": true, "event_id": "EVENT_ID" },
    "stats": [
      { "stat": { "id": 1, "name": "points", "display_name": "Points", "abbreviation": "PTS", "sport_id": 4 }, "value": "28" },
      { "stat": { "id": 3, "name": "assists", "display_name": "Assists", "abbreviation": "AST", "sport_id": 4 }, "value": "10" }
    ]
  }
]

Player REST rows omit IDs already represented by the group: use player.id for the owner, meta.event_id for the event, and stat.id for the stat key. Live WebSocket rows additionally carry explicit player_id and stat_id fields.

MLB game-stat definitions include startingPitcher and the sparse positionPlayerPitching flag. Query GET /api/v2/stats?sport_id=3 to discover their current IDs; do not hard-code IDs.

Stats at Different Levels

Level	Endpoint	Description
Definitions	`GET /api/v2/stats`	What stats exist and their IDs
Team game	`GET /api/v2/events/{eventID}/stats`	Team box score for one game
Player game	`GET /api/v2/events/{eventID}/players/stats`	Player box score for one game
Team season	`GET /api/v2/teams/{teamID}/stats`	Aggregate team stats for a season
Player season	`GET /api/v2/teams/{teamID}/players/stats`	Per-player season stats for a team

V2 Sports

V2 Events

V2 Markets

V2 Futures

V2 Teams

V2 Players

V2 Stats

V2 Reference

V2 WebSocket

V1 Events (Legacy)

V1 Lines (Legacy)

V1 Sports (Legacy)

V1 Delta (Legacy)

V1 Reference (Legacy)

V1 WebSocket (Legacy)

Overview

Live Game Stats over WebSocket

Endpoints

Parameters

Example Response

Parameters

Example Response

Parameters

Example Response

Stats at Different Levels

​Overview

​Live Game Stats over WebSocket

​Endpoints

​Parameters

​Example Response

​Parameters

​Example Response

​Parameters

​Example Response

​Stats at Different Levels

Overview

Live Game Stats over WebSocket

Endpoints

Parameters

Example Response

Parameters

Example Response

Parameters

Example Response

Stats at Different Levels