Stats API Documentation

The Stats API provides read-only access to detailed fight statistics, bot career data, tournament aggregates, head-to-head records, and leaderboards. No authentication is required. All responses are JSON.

Base URL: /api.php/stats

This extends the existing BrettZone API. The original tournament/fight/player/video endpoints remain at /api.php.

Endpoints

Fight Stats Bot Career Stats Tournament Stats Head-to-Head Leaderboard

Fight Stats

Get detailed stats for a single fight including timing, pause info, judges scorecard, and per-player data.

GET /api.php/stats/fight/{tournamentID}/{gameID}

Parameter	Location	Description
`tournamentID` required	path	Tournament ID (e.g. `nhrl_mar26_12lb`)
`gameID` required	path	Game/fight ID (e.g. `W-14`)

Response Fields

matchDurationSeconds Actual duration (stopTime - startTime)
timerDuration Timer/clock duration from game system
wasPaused Boolean -- whether the fight was paused
countdown Countdown timer value
winMethod How the fight was won (KO, JD, TKO, etc.)
judgesScorecard Array of {bot, category, rating} parsed from judges string
players[] Per-player: name, score, isWinner, unstickTime, showMotionTime
cameraCount Number of camera angles recorded
roundName Name of the round (e.g. "Final", "Semi-Final")

Try It

Tournament ID

Game ID

Bot Career Stats

Aggregate stats for a bot across all public tournaments: wins, losses, win rate, KO breakdown, average fight duration, and recent fights.

GET /api.php/stats/bot/{botName}

Parameter	Location	Description
`botName` required	path	Bot's clean name -- lowercase, alphanumeric only (e.g. `void`, `cherri`)

Response Fields

totalWins / totalLosses / winRate Career record
totalFights / totalTournaments Overall participation
winMethodBreakdown Object of win method counts (e.g. {"KO": 5, "JD": 3})
durationStats All timing data grouped together:

durationStats.averageSeconds Mean fight length
durationStats.medianSeconds Median fight length
durationStats.totalFightTimeSeconds Sum of all fight durations
durationStats.fightsMeasured Fights with valid timing data
durationStats.longestFight With gameID, tournamentID, opponent, duration
durationStats.shortestFight With gameID, tournamentID, opponent, duration

weightClasses Array of weight classes fought in
recentFights Last 5 fights with opponent, result, method, duration

Tip: Getting fight duration stats for a bot

Use the durationStats object to get average, median, longest, and shortest fight times for any bot. For example, /api.php/stats/bot/caldera returns durationStats.averageSeconds, durationStats.medianSeconds, plus the longest and shortest fights with opponent names and game IDs. The top-level avgMatchDurationSeconds, longestFight, and shortestFight fields are still available for backwards compatibility.

Try It

Bot Name

Tournament Stats

Aggregate statistics for an entire tournament: fight counts, average duration, win method breakdown, longest/shortest fights, and pause counts.

GET /api.php/stats/tournament/{tournamentID}

Parameter	Location	Description
`tournamentID` required	path	Tournament ID (e.g. `nhrl_mar26_12lb`)

Response Fields

totalFights / completedFights Total and completed fight counts
avgMatchDurationSeconds Average completed fight duration
winMethodBreakdown Object of win method counts
totalPausedFights Number of fights that had a pause
longestFight / shortestFight With player names, gameID, duration

Try It

Tournament ID

Head-to-Head

Compare two bots across all their meetings: win counts, fight-by-fight history with results, methods, and durations.

GET /api.php/stats/head-to-head/{bot1}/{bot2}

Parameter	Location	Description
`bot1` required	path	First bot's clean name
`bot2` required	path	Second bot's clean name

Response Fields

bot1Name / bot2Name Display names
totalMeetings How many times they've fought
bot1Wins / bot2Wins / draws Win counts
meetings[] Each fight: tournament, winner, method, duration, scores

Try It

Bot 1

Bot 2

Leaderboard

Ranked lists of bots by various metrics. Win rate and KO rate require a minimum of 3 fights.

GET /api.php/stats/leaderboard?metric=wins&weightClass=12&limit=20

Parameter	Location	Description
`metric` optional	query	Ranking metric: `wins` (default), `winRate`, `koRate`, `avgMatchDuration`
`weightClass` optional	query	Filter by weight class in lbs (e.g. `3`, `12`, `30`)
`limit` optional	query	Number of results (default: 20, max: 100)

Available Metrics

wins Total wins across all tournaments
winRate Win percentage (min 3 fights)
koRate KO win percentage (min 3 wins)
avgMatchDuration Average fight length, shortest first (min 3 fights)

Try It

Metric

Weight Class

Limit

Data Reference

Common data types and enumerations used across the Stats API.

Win Methods

Value	Description
`KO`	Knockout
`JD`	Judges Decision
`TKO`	Technical Knockout
`FF`	Forfeit

Judges Scorecard Categories

Category	Possible Ratings
`weapon`	full, partial, disabled
`drive`	full, partial, disabled

Time Fields

All timestamps are Unix timestamps (seconds since epoch). Duration fields are in seconds. startTime / stopTime are the fight clock start and stop.

Bot Names

When passing a bot name in URLs, use the clean name: lowercase with only alphanumeric characters. For example, "Dr. Doom III" becomes drdoomiii. The API will strip non-alphanumeric characters for you.