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.4---5
6# PvP API (Retail — Patch 12.0.0)
7
8Comprehensive reference for PvP, battlegrounds, arenas, rated PvP, war mode, and duels.
9
10> **Source:** https://warcraft.wiki.gg/wiki/World_of_Warcraft_API
11> **Current as of:** Patch 12.0.0 (Build 65655) — January 28, 2026
12> **Scope:** Retail only.
13
14---
15
16## Scope
17
18- **C_PvP** — PvP info, rated stats, rewards, queuing
19- **Battlegrounds** — BG state, score, flags
20- **Arenas** — Arena info, teams, ratings
21- **War Mode** — War mode toggle, bonuses
22- **Duels** — Accept, cancel, start
23- **Honor/Conquest** — Currency tracking
24
25---
26
27## C_PvP — Core PvP System
28
29### PvP State & Info
30
31| 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 |
52
53### Rated PvP
54
55| 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 |
70
71### Honor & Conquest
72
73| 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 |
82
83### Battleground Score
84
85| 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 |
92
93### Battleground/Arena Queue
94
95| 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 |
108
109---
110
111## Duel Functions
112
113| Function | Returns | Description |
114|----------|---------|-------------|
115| `AcceptDuel()` | — | Accept duel request |
116| `CancelDuel()` | — | Decline/cancel duel |
117| `StartDuel(unit)` | — | Request duel |
118
119---
120
121## War Game Functions
122
123| Function | Returns | Description |
124|----------|---------|-------------|
125| `C_PvP.StartWarGame(targetName, warGameType, ...)` | — | Start war game |
126| `C_PvP.IsWarGameByMasterAllowed()` | `allowed` | Can start war games? |
127
128---
129
130## Common Patterns
131
132### Check PvP Context
133
134```lua
135local 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" end
140end
141```
142
143### Display Rated PvP Info
144
145```lua
146local function PrintRatedInfo()
147 local season = C_PvP.GetCurrentSeasonNumber()
148 print("PvP Season:", season)
149
150 -- Check bracket ratings
151 for bracketIndex = 1, 4 do
152 local tierID = C_PvP.GetPvpTierID(bracketIndex, UnitGUID("player"))
153 if tierID then
154 local tierInfo = C_PvP.GetPvpTierInfo(tierID)
155 if tierInfo then
156 print("Bracket", bracketIndex, ":", tierInfo.pvpTierEnum, tierInfo.tierName)
157 end
158 end
159 end
160end
161```
162
163---
164
165## Key Events
166
167| 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 |
191
192---
193
194## Gotchas & Restrictions
195
1961. **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.
JBurlison