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.Accounts created on or after
2026-09-07T18:00:00Z follow the new stats-access policy. Accounts created before that cutoff retain their existing legacy stats access. The stat dictionary remains available to every authenticated key; new Free accounts receive a default seven-day current-season completed-box evaluation, while production REST access otherwise depends on effective stats features. See Stats Access for the current matrix, fixed sample, coverage limits, and 403 handling.Event completion for grading
Game-stat completion is event-level:meta.complete: true on a returned REST team or player group means the box score for meta.event_id is finalized for grading. The flag is repeated on groups; it does not describe just that team’s or player’s progress. Require explicit completion and validate the fields needed for your result. A final score status, missing flag, or empty response is not a substitute. See Event completion for grading for REST and WebSocket examples.
Live Game Stats over WebSocket
On Ultra plans and higher, subscribe to thestats channel on the multiplexed endpoint:
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_statsframes. - Fetch the current team box from
GET /api/v2/events/{eventID}/statsand player box fromGET /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: trueis the terminal completion marker; mark the cached box complete and treat repeats as idempotent. A zero-row frame withoutcomplete: trueis an invalidation fallback; refetch both REST resources.
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/sample — Fixed complete-game sample
GET /api/v2/stats/sample — Fixed complete-game sample
Returns a static, marked sample box score for schema and parsing tests. It requires an API key but consumes no data points. The sample is not a production-data entitlement and does not establish live, historical, sport, or event coverage.Use it once to verify your integration. Do not poll this route; use the relevant production route only after confirming effective account access.
GET /api/v2/stats — List all stat definitions
GET /api/v2/stats — List all stat definitions
GET /api/v2/events/{eventID}/stats — Team game stats
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
Example Response
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
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
Example Response
Example truncated to two players.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
The current-season aggregate is the latest published value and can include in-progress activity. If a
year is supplied, archive availability depends on the sport’s actual coverage. Player season results use current roster association and do not guarantee historical team attribution; event game boxes retain the teams recorded for that event.