1---2name: wow-api-pvp3description: Complete reference for WoW Retail PvP, Battlegrounds, Arenas, Rated PvP, War Mode, Duels, War Games, and Honor/Conquest APIs. Covers C_PvP (PvP info, rated stats, rewards, battlegrounds, arenas, war mode, brawls, special events), duel functions (AcceptDuel, CancelDuel, StartDuel), war game functions, honor/conquest tracking, PvP talent integration, and PvP-related events. Use when working with PvP systems, battlegrounds, arenas, rated PvP, war mode, honor, conquest, duels, or PvP UI. Use when this capability is needed.4---56# PvP API (Retail — Patch 12.0.0)78Comprehensive reference for PvP, battlegrounds, arenas, rated PvP, war mode, and duels.910> **Source:** https://warcraft.wiki.gg/wiki/World_of_Warcraft_API11> **Current as of:** Patch 12.0.0 (Build 65655) — January 28, 202612> **Scope:** Retail only.1314---1516## Scope1718- **C_PvP** — PvP info, rated stats, rewards, queuing19- **Battlegrounds** — BG state, score, flags20- **Arenas** — Arena info, teams, ratings21- **War Mode** — War mode toggle, bonuses22- **Duels** — Accept, cancel, start23- **Honor/Conquest** — Currency tracking2425---2627## C_PvP — Core PvP System2829### PvP State & Info3031| Function | Returns | Description |32|----------|---------|-------------|33| `C_PvP.IsPVPMap()` | `isPVP` | In a PvP map? |34| `C_PvP.IsInPVPBattleground()` | `inBG` | In a battleground? (deprecated name for `IsInBattleground`) |35| `C_PvP.IsInBattleground()` | `inBG` | In a battleground? |36| `C_PvP.IsBattleground()` | `isBG` | Current zone is BG? |37| `C_PvP.IsArena()` | `isArena` | In an arena? |38| `C_PvP.IsSoloShuffle()` | `isSoloShuffle` | In solo shuffle? |39| `C_PvP.IsBlitz()` | `isBlitz` | In blitz BG? |40| `C_PvP.IsRatedBattleground()` | `isRated` | In rated BG? |41| `C_PvP.IsRatedArena()` | `isRated` | In rated arena? |42| `C_PvP.IsRatedMap()` | `isRated` | In any rated match? |43| `C_PvP.IsWarModeDesired()` | `isDesired` | War mode toggled on? |44| `C_PvP.IsWarModeActive()` | `isActive` | War mode currently active? |45| `C_PvP.IsWarModeFeatureEnabled()` | `isEnabled` | War mode feature available? |46| `C_PvP.CanToggleWarMode(toggle)` | `canToggle` | Can toggle war mode? |47| `C_PvP.ToggleWarMode()` | — | Toggle war mode |48| `C_PvP.GetWarModeRewardBonus()` | `bonusPercent` | War mode XP/resource bonus % |49| `C_PvP.IsPvPTalentsUnlocked()` | `isUnlocked` | PvP talents available? |50| `C_PvP.GetPVPActiveMatchDuration()` | `duration` | Active match duration |51| `C_PvP.GetPVPActiveMatchState()` | `state` | Match state |5253### Rated PvP5455| Function | Returns | Description |56|----------|---------|-------------|57| `C_PvP.GetRatedBGRewards()` | `rewardInfo` | Rated BG rewards |58| `C_PvP.GetArenaRewards(teamSize)` | `rewardInfo` | Arena rewards |59| `C_PvP.GetSeasonBestInfo()` | `tierID, nextTierID` | Season best tier |60| `C_PvP.GetCurrentSeasonNumber()` | `season` | Current PvP season |61| `C_PvP.GetRankInfo(hk, guid)` | `rankName, rankNumber` | PvP rank info |62| `C_PvP.GetGlobalPvpScalingInfoForSpecID(specID)` | `info` | PvP scaling |63| `C_PvP.GetLevelUpBattlegrounds()` | `bgIDs` | Available BGs for level |64| `C_PvP.GetRandomBGInfo()` | `info` | Random BG info |65| `C_PvP.GetRandomBGRewards()` | `rewardInfo` | Random BG rewards |66| `C_PvP.GetRandomEpicBGInfo()` | `info` | Random epic BG info |67| `C_PvP.GetSkirmishInfo(bracketIndex)` | `info` | Skirmish info |68| `C_PvP.GetPvpTierInfo(tierID)` | `tierInfo` | PvP tier details |69| `C_PvP.GetPvpTierID(bracketIndex, guid)` | `tierID` | Player's tier in bracket |7071### Honor & Conquest7273| Function | Returns | Description |74|----------|---------|-------------|75| `C_PvP.GetHonorRewardInfo(honorLevel)` | `rewardInfo` | Honor level reward |76| `GetHonorLevel()` | `level` | Current honor level |77| `UnitHonorLevel(unit)` | `level` | Unit's honor level |78| `GetMaxPlayerHonorLevel()` | `maxLevel` | Max honor level |79| `GetPVPLifetimeStats()` | `hk, dk, highestRank` | Lifetime PvP stats |80| `GetPVPSessionStats()` | `hk, dk` | Session PvP stats |81| `GetPVPYesterdayStats()` | `hk, dk, honor` | Yesterday's stats |8283### Battleground Score8485| Function | Returns | Description |86|----------|---------|-------------|87| `GetNumBattlefieldScores()` | `numScores` | Score entries |88| `GetBattlefieldScore(index)` | `name, killingBlows, honorKills, deaths, honorGained, faction, race, class, classToken, damageDone, healingDone, bgRating, ratingChange, preMatchMMR, mmrChange, talentSpec` | Score info |89| `GetBattlefieldStatData(index, statIndex)` | `value` | BG-specific stat |90| `GetNumBattlefieldStats()` | `numStats` | BG stat columns |91| `GetBattlefieldStatInfo(statIndex)` | `name, icon, tooltip` | Stat column info |9293### Battleground/Arena Queue9495| Function | Returns | Description |96|----------|---------|-------------|97| `C_PvP.RequestCrowdControlSpell(unitToken)` | — | Request CC info |98| `JoinBattlefield(index [, asGroup [, isRated]])` | — | Join BG queue |99| `LeaveBattlefield()` | — | Leave BG |100| `AcceptBattlefieldPort(index, acceptFlag)` | — | Accept/decline BG port |101| `GetBattlefieldPortExpiration(index)` | `expiration` | Port expiration time |102| `GetBattlefieldStatus(index)` | `status, mapName, teamSize, registeredMatch, suspendedQueue, queueType, gameID, role, asGroup, shortDescription, longDescription` | Queue status |103| `GetMaxBattlefieldID()` | `maxID` | Max battlefield ID |104| `GetBattlefieldInstanceRunTime()` | `runTime` | Instance elapsed ms |105| `GetBattlefieldTimeWaited(index)` | `timeWaited` | Time in queue |106| `GetBattlefieldEstimatedWaitTime(index)` | `waitTime` | Estimated wait |107| `GetBattlefieldWinner()` | `winner` | Winning faction |108109---110111## Duel Functions112113| Function | Returns | Description |114|----------|---------|-------------|115| `AcceptDuel()` | — | Accept duel request |116| `CancelDuel()` | — | Decline/cancel duel |117| `StartDuel(unit)` | — | Request duel |118119---120121## War Game Functions122123| Function | Returns | Description |124|----------|---------|-------------|125| `C_PvP.StartWarGame(targetName, warGameType, ...)` | — | Start war game |126| `C_PvP.IsWarGameByMasterAllowed()` | `allowed` | Can start war games? |127128---129130## Common Patterns131132### Check PvP Context133134```lua135local function GetPvPContext()136 if C_PvP.IsArena() then return "arena"137 elseif C_PvP.IsInBattleground() then return "battleground"138 elseif C_PvP.IsWarModeActive() then return "warmode"139 else return "pve" end140end141```142143### Display Rated PvP Info144145```lua146local function PrintRatedInfo()147 local season = C_PvP.GetCurrentSeasonNumber()148 print("PvP Season:", season)149 150 -- Check bracket ratings151 for bracketIndex = 1, 4 do152 local tierID = C_PvP.GetPvpTierID(bracketIndex, UnitGUID("player"))153 if tierID then154 local tierInfo = C_PvP.GetPvpTierInfo(tierID)155 if tierInfo then156 print("Bracket", bracketIndex, ":", tierInfo.pvpTierEnum, tierInfo.tierName)157 end158 end159 end160end161```162163---164165## Key Events166167| Event | Payload | Description |168|-------|---------|-------------|169| `PVP_MATCH_ACTIVE` | — | PvP match started |170| `PVP_MATCH_COMPLETE` | winner | Match ended |171| `PVP_MATCH_INACTIVE` | — | Match inactive |172| `UPDATE_BATTLEFIELD_STATUS` | battlefieldIndex | Queue status changed |173| `UPDATE_BATTLEFIELD_SCORE` | — | Scoreboard updated |174| `BATTLEFIELD_QUEUE_TIMEOUT` | — | Queue timed out |175| `WARGAME_REQUESTED` | opposingPartyMemberName, bgName, timeout, tournamentRules | War game request |176| `DUEL_REQUESTED` | playerName | Duel request received |177| `DUEL_FINISHED` | — | Duel ended |178| `DUEL_INBOUNDS` | — | Player in duel bounds |179| `DUEL_OUTOFBOUNDS` | — | Player out of bounds |180| `HONOR_LEVEL_UPDATE` | isHigherLevel | Honor level changed |181| `PVP_RATED_STATS_UPDATE` | — | Rated stats updated |182| `PVP_REWARDS_UPDATE` | — | PvP rewards updated |183| `WAR_MODE_STATUS_UPDATE` | isWarModeDesired | War mode toggled |184| `PLAYER_FLAGS_CHANGED` | unitTarget | PvP flag changed |185| `PVP_TIMER_UPDATE` | — | PvP timer updated |186| `PVP_VEHICLE_INFO_UPDATED` | — | PvP vehicle info changed |187| `PVP_WORLDSTATE_UPDATE` | — | World state updated |188| `ARENA_OPPONENT_UPDATE` | unitToken, updateReason | Arena opponent updated |189| `ARENA_PREP_OPPONENT_SPECIALIZATIONS` | — | Arena opponent specs |190| `ARENA_SEASON_WORLD_STATE` | — | Arena season state |191192---193194## Gotchas & Restrictions1951961. **War mode toggle location** — Can only toggle war mode in Stormwind/Orgrimmar (capital cities), not anywhere.1972. **BG score indices** — `GetBattlefieldScore()` indices are 1-based and may not match player order.1983. **Queue index** — `GetBattlefieldStatus()` uses queue index (1-based), not battlefield ID.1994. **PvP talents** — PvP talents are managed through `C_SpecializationInfo`, not `C_PvP`. See the talents skill.2005. **AcceptBattlefieldPort hardware event** — Requires a hardware event to accept.2016. **12.0.0 instance restrictions** — In BGs and arenas, enemy player info (name, class, health) may be secret values.2027. **Honor is a currency** — Honor and conquest are currencies. Use `C_CurrencyInfo` for tracking amounts.2038. **Season resets** — Rated PvP data resets each season. `GetCurrentSeasonNumber()` tracks the season.204205---206> Converted and distributed by [TomeVault](https://tomevault.io/claim/jburlison) — claim your Tome and manage your conversions.207<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io