1---
2name: wow-api-pvp
3description: "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."
4metadata:
5 source: https://skillmd.com/skills/jburlison/wow-api-pvp
6---
7
8# PvP API (Retail — Patch 12.0.0)
9
10Comprehensive reference for PvP, battlegrounds, arenas, rated PvP, war mode, and duels.
11
12> **Source:** https://warcraft.wiki.gg/wiki/World_of_Warcraft_API
13> **Current as of:** Patch 12.0.0 (Build 65655) — January 28, 2026
14> **Scope:** Retail only.
15
16---
17
18## Scope
19
20- **C_PvP** — PvP info, rated stats, rewards, queuing
21- **Battlegrounds** — BG state, score, flags
22- **Arenas** — Arena info, teams, ratings
23- **War Mode** — War mode toggle, bonuses
24- **Duels** — Accept, cancel, start
25- **Honor/Conquest** — Currency tracking
26
27---
28
29## C_PvP — Core PvP System
30
31### PvP State & Info
32
33| Function | Returns | Description |
34|----------|---------|-------------|
35| `C_PvP.IsPVPMap()` | `isPVP` | In a PvP map? |
36| `C_PvP.IsInPVPBattleground()` | `inBG` | In a battleground? (deprecated name for `IsInBattleground`) |
37| `C_PvP.IsInBattleground()` | `inBG` | In a battleground? |
38| `C_PvP.IsBattleground()` | `isBG` | Current zone is BG? |
39| `C_PvP.IsArena()` | `isArena` | In an arena? |
40| `C_PvP.IsSoloShuffle()` | `isSoloShuffle` | In solo shuffle? |
41| `C_PvP.IsBlitz()` | `isBlitz` | In blitz BG? |
42| `C_PvP.IsRatedBattleground()` | `isRated` | In rated BG? |
43| `C_PvP.IsRatedArena()` | `isRated` | In rated arena? |
44| `C_PvP.IsRatedMap()` | `isRated` | In any rated match? |
45| `C_PvP.IsWarModeDesired()` | `isDesired` | War mode toggled on? |
46| `C_PvP.IsWarModeActive()` | `isActive` | War mode currently active? |
47| `C_PvP.IsWarModeFeatureEnabled()` | `isEnabled` | War mode feature available? |
48| `C_PvP.CanToggleWarMode(toggle)` | `canToggle` | Can toggle war mode? |
49| `C_PvP.ToggleWarMode()` | — | Toggle war mode |
50| `C_PvP.GetWarModeRewardBonus()` | `bonusPercent` | War mode XP/resource bonus % |
51| `C_PvP.IsPvPTalentsUnlocked()` | `isUnlocked` | PvP talents available? |
52| `C_PvP.GetPVPActiveMatchDuration()` | `duration` | Active match duration |
53| `C_PvP.GetPVPActiveMatchState()` | `state` | Match state |
54
55### Rated PvP
56
57| Function | Returns | Description |
58|----------|---------|-------------|
59| `C_PvP.GetRatedBGRewards()` | `rewardInfo` | Rated BG rewards |
60| `C_PvP.GetArenaRewards(teamSize)` | `rewardInfo` | Arena rewards |
61| `C_PvP.GetSeasonBestInfo()` | `tierID, nextTierID` | Season best tier |
62| `C_PvP.GetCurrentSeasonNumber()` | `season` | Current PvP season |
63| `C_PvP.GetRankInfo(hk, guid)` | `rankName, rankNumber` | PvP rank info |
64| `C_PvP.GetGlobalPvpScalingInfoForSpecID(specID)` | `info` | PvP scaling |
65| `C_PvP.GetLevelUpBattlegrounds()` | `bgIDs` | Available BGs for level |
66| `C_PvP.GetRandomBGInfo()` | `info` | Random BG info |
67| `C_PvP.GetRandomBGRewards()` | `rewardInfo` | Random BG rewards |
68| `C_PvP.GetRandomEpicBGInfo()` | `info` | Random epic BG info |
69| `C_PvP.GetSkirmishInfo(bracketIndex)` | `info` | Skirmish info |
70| `C_PvP.GetPvpTierInfo(tierID)` | `tierInfo` | PvP tier details |
71| `C_PvP.GetPvpTierID(bracketIndex, guid)` | `tierID` | Player's tier in bracket |
72
73### Honor & Conquest
74
75| Function | Returns | Description |
76|----------|---------|-------------|
77| `C_PvP.GetHonorRewardInfo(honorLevel)` | `rewardInfo` | Honor level reward |
78| `GetHonorLevel()` | `level` | Current honor level |
79| `UnitHonorLevel(unit)` | `level` | Unit's honor level |
80| `GetMaxPlayerHonorLevel()` | `maxLevel` | Max honor level |
81| `GetPVPLifetimeStats()` | `hk, dk, highestRank` | Lifetime PvP stats |
82| `GetPVPSessionStats()` | `hk, dk` | Session PvP stats |
83| `GetPVPYesterdayStats()` | `hk, dk, honor` | Yesterday's stats |
84
85### Battleground Score
86
87| Function | Returns | Description |
88|----------|---------|-------------|
89| `GetNumBattlefieldScores()` | `numScores` | Score entries |
90| `GetBattlefieldScore(index)` | `name, killingBlows, honorKills, deaths, honorGained, faction, race, class, classToken, damageDone, healingDone, bgRating, ratingChange, preMatchMMR, mmrChange, talentSpec` | Score info |
91| `GetBattlefieldStatData(index, statIndex)` | `value` | BG-specific stat |
92| `GetNumBattlefieldStats()` | `numStats` | BG stat columns |
93| `GetBattlefieldStatInfo(statIndex)` | `name, icon, tooltip` | Stat column info |
94
95### Battleground/Arena Queue
96
97| Function | Returns | Description |
98|----------|---------|-------------|
99| `C_PvP.RequestCrowdControlSpell(unitToken)` | — | Request CC info |
100| `JoinBattlefield(index [, asGroup [, isRated]])` | — | Join BG queue |
101| `LeaveBattlefield()` | — | Leave BG |
102| `AcceptBattlefieldPort(index, acceptFlag)` | — | Accept/decline BG port |
103| `GetBattlefieldPortExpiration(index)` | `expiration` | Port expiration time |
104| `GetBattlefieldStatus(index)` | `status, mapName, teamSize, registeredMatch, suspendedQueue, queueType, gameID, role, asGroup, shortDescription, longDescription` | Queue status |
105| `GetMaxBattlefieldID()` | `maxID` | Max battlefield ID |
106| `GetBattlefieldInstanceRunTime()` | `runTime` | Instance elapsed ms |
107| `GetBattlefieldTimeWaited(index)` | `timeWaited` | Time in queue |
108| `GetBattlefieldEstimatedWaitTime(index)` | `waitTime` | Estimated wait |
109| `GetBattlefieldWinner()` | `winner` | Winning faction |
110
111---
112
113## Duel Functions
114
115| Function | Returns | Description |
116|----------|---------|-------------|
117| `AcceptDuel()` | — | Accept duel request |
118| `CancelDuel()` | — | Decline/cancel duel |
119| `StartDuel(unit)` | — | Request duel |
120
121---
122
123## War Game Functions
124
125| Function | Returns | Description |
126|----------|---------|-------------|
127| `C_PvP.StartWarGame(targetName, warGameType, ...)` | — | Start war game |
128| `C_PvP.IsWarGameByMasterAllowed()` | `allowed` | Can start war games? |
129
130---
131
132## Common Patterns
133
134### Check PvP Context
135
136```lua
137local function GetPvPContext()
138 if C_PvP.IsArena() then return "arena"
139 elseif C_PvP.IsInBattleground() then return "battleground"
140 elseif C_PvP.IsWarModeActive() then return "warmode"
141 else return "pve" end
142end
143```
144
145### Display Rated PvP Info
146
147```lua
148local function PrintRatedInfo()
149 local season = C_PvP.GetCurrentSeasonNumber()
150 print("PvP Season:", season)
151
152 -- Check bracket ratings
153 for bracketIndex = 1, 4 do
154 local tierID = C_PvP.GetPvpTierID(bracketIndex, UnitGUID("player"))
155 if tierID then
156 local tierInfo = C_PvP.GetPvpTierInfo(tierID)
157 if tierInfo then
158 print("Bracket", bracketIndex, ":", tierInfo.pvpTierEnum, tierInfo.tierName)
159 end
160 end
161 end
162end
163```
164
165---
166
167## Key Events
168
169| Event | Payload | Description |
170|-------|---------|-------------|
171| `PVP_MATCH_ACTIVE` | — | PvP match started |
172| `PVP_MATCH_COMPLETE` | winner | Match ended |
173| `PVP_MATCH_INACTIVE` | — | Match inactive |
174| `UPDATE_BATTLEFIELD_STATUS` | battlefieldIndex | Queue status changed |
175| `UPDATE_BATTLEFIELD_SCORE` | — | Scoreboard updated |
176| `BATTLEFIELD_QUEUE_TIMEOUT` | — | Queue timed out |
177| `WARGAME_REQUESTED` | opposingPartyMemberName, bgName, timeout, tournamentRules | War game request |
178| `DUEL_REQUESTED` | playerName | Duel request received |
179| `DUEL_FINISHED` | — | Duel ended |
180| `DUEL_INBOUNDS` | — | Player in duel bounds |
181| `DUEL_OUTOFBOUNDS` | — | Player out of bounds |
182| `HONOR_LEVEL_UPDATE` | isHigherLevel | Honor level changed |
183| `PVP_RATED_STATS_UPDATE` | — | Rated stats updated |
184| `PVP_REWARDS_UPDATE` | — | PvP rewards updated |
185| `WAR_MODE_STATUS_UPDATE` | isWarModeDesired | War mode toggled |
186| `PLAYER_FLAGS_CHANGED` | unitTarget | PvP flag changed |
187| `PVP_TIMER_UPDATE` | — | PvP timer updated |
188| `PVP_VEHICLE_INFO_UPDATED` | — | PvP vehicle info changed |
189| `PVP_WORLDSTATE_UPDATE` | — | World state updated |
190| `ARENA_OPPONENT_UPDATE` | unitToken, updateReason | Arena opponent updated |
191| `ARENA_PREP_OPPONENT_SPECIALIZATIONS` | — | Arena opponent specs |
192| `ARENA_SEASON_WORLD_STATE` | — | Arena season state |
193
194---
195
196## Gotchas & Restrictions
197
1981. **War mode toggle location** — Can only toggle war mode in Stormwind/Orgrimmar (capital cities), not anywhere.
1992. **BG score indices** — `GetBattlefieldScore()` indices are 1-based and may not match player order.
2003. **Queue index** — `GetBattlefieldStatus()` uses queue index (1-based), not battlefield ID.
2014. **PvP talents** — PvP talents are managed through `C_SpecializationInfo`, not `C_PvP`. See the talents skill.
2025. **AcceptBattlefieldPort hardware event** — Requires a hardware event to accept.
2036. **12.0.0 instance restrictions** — In BGs and arenas, enemy player info (name, class, health) may be secret values.
2047. **Honor is a currency** — Honor and conquest are currencies. Use `C_CurrencyInfo` for tracking amounts.
2058. **Season resets** — Rated PvP data resets each season. `GetCurrentSeasonNumber()` tracks the season.