wow-api-encounters

name

wow-api-encounters

description

Complete reference for WoW Retail Encounter Journal, Mythic+/Challenge Mode, Instance, Scenario, Raid Lock, and Season APIs. Covers EncounterJournal (dungeon/raid boss database, loot tables, section navigation), C_ChallengeMode (M+ keystones, affixes, timers, best times), C_MythicPlus (weekly runs, seasonal data, rating), ScenarioInfo (delves/scenarios objectives and stages), InstanceLeaverInfo (deserter), RaidLocks (saved instances), C_SeasonInfo (seasonal info), and related events. Use when working with dungeon/raid encounter data, M+ keystones, mythic plus scores, scenario stages, raid lockouts, or seasonal content.

Encounters API (Retail — Patch 12.0.0)

Comprehensive reference for encounter journal, mythic+, instances, scenarios, raid locks, and seasons.

Source: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API Current as of: Patch 12.0.0 (Build 65655) — January 28, 2026 Scope: Retail only.

---

Scope

• Encounter Journal — Boss database, loot tables, abilities
• C_ChallengeMode — M+ keystones, affixes, timers
• C_MythicPlus — Weekly M+ runs, rating, seasonal
• ScenarioInfo — Scenarios, delves, stages
• InstanceLeaverInfo — Deserter/leaver info
• Raid Locks — Saved instance lockouts
• C_SeasonInfo — Seasonal content

---

Encounter Journal

Instance Navigation

Function	Returns	Description
EJ_GetNumTiers()	numTiers	Number of expansion tiers
EJ_GetTierInfo(tierIndex)	name, link	Tier name and link
EJ_SelectTier(tierIndex)	—	Select expansion tier
EJ_GetCurrentTier()	tierIndex	Current selected tier
EJ_GetInstanceByIndex(index, isRaid)	instanceID, name, description, bgImage, buttonImage1, loreImage, buttonImage2, dungeonAreaMapID, link, shouldDisplayDifficulty	Instance at index
EJ_GetNumInstances()	—	Not a function; iterate EJ_GetInstanceByIndex until nil
EJ_SelectInstance(instanceID)	—	Select instance
EJ_GetInstanceInfo(instanceID)	name, description, bgImage, ...	Instance info
EJ_InstanceIsRaid()	isRaid	Selected is raid?

Encounter (Boss) Data

Function	Returns	Description
EJ_GetEncounterInfoByIndex(index)	name, description, journalEncounterID, rootSectionID, link, journalInstanceID, dungeonEncounterID, instanceID	Boss at index
EJ_GetEncounterInfo(encounterID)	name, description, journalEncounterID, rootSectionID, link, journalInstanceID, dungeonEncounterID, instanceID	Boss info
EJ_SelectEncounter(encounterID)	—	Select encounter
EJ_GetNumEncountersForLootByIndex(index)	numEncounters	Bosses with loot
EJ_GetCreatureInfo(index, encounterID)	id, name, description, displayInfo, iconImage, ...	Creature info

Section (Ability) Data

Function	Returns	Description
EJ_GetSectionInfo(sectionID)	info	Section/ability info
EJ_GetNumSectionsForEncounter(encounterID)	numSections	Number of sections

Section Info Fields

• title — Section title
• description — Section text
• headerType — Header type enum
• abilityIcon — Icon texture
• creatureDisplayID — Display ID
• siblingSectionID — Next sibling
• firstChildSectionID — First child
• filteredByDifficulty — Hidden by difficulty filter?
• link — Journal link
• startsOpen — Default expanded?

Loot

Function	Returns	Description
EJ_GetLootInfoByIndex(index)	name, icon, slotFilter, armorType, itemID, link, encounterID	Loot at index
EJ_GetNumLoot()	numLoot	Number of loot items
EJ_SetLootFilter(classID, specID)	—	Filter by class/spec
EJ_GetLootFilter()	classID, specID	Current filter
EJ_SetSlotFilter(slotFilter)	—	Filter by slot
EJ_GetSlotFilter()	slotFilter	Current slot filter
EJ_ResetLootFilter()	—	Clear all filters
EJ_IsLootListOutOfDate()	isOutOfDate	Needs refresh?

Difficulty

Function	Returns	Description
EJ_SetDifficulty(difficultyID)	—	Set EJ difficulty
EJ_GetDifficulty()	difficultyID	Current EJ difficulty
EJ_GetNumEncountersByDifficulty(difficultyID)	numEncounters	Bosses at difficulty

Search

Function	Returns	Description
EJ_SetSearch(text)	—	Set search text
EJ_GetSearchResult(index)	resultInfo	Search result
EJ_GetNumSearchResults()	numResults	Num results
EJ_IsSearchFinished()	isFinished	Search done?
EJ_ClearSearch()	—	Clear search

---

C_ChallengeMode — Mythic+ Keystones

Keystone Info

Function	Returns	Description
C_ChallengeMode.GetActiveKeystoneInfo()	activeKeystoneLevel, activeAffixIDs, wasActiveKeystoneCharged	Active keystone
C_ChallengeMode.GetActiveChallengeMapID()	mapID	Active M+ map
C_ChallengeMode.GetActiveKeystoneLink()	link	Keystone hyperlink
C_ChallengeMode.GetSlottedKeystoneInfo()	mapID, affixIDs, keystoneLevel	Slotted keystone
C_ChallengeMode.HasSlottedKeystone()	hasKeystone	Keystone slotted?
C_ChallengeMode.SlotKeystone()	slotted	Slot keystone
C_ChallengeMode.RemoveKeystone()	removed	Remove keystone

Map & Affix Data

Function	Returns	Description
C_ChallengeMode.GetMapTable()	mapIDs	All M+ maps
C_ChallengeMode.GetMapUIInfo(mapID)	name, id, timeLimit, texture, backgroundTexture	Map info
C_ChallengeMode.GetAffixInfo(affixID)	name, description, filedataid	Affix info
C_ChallengeMode.GetCurrentAffixes()	affixes	This week's affixes

Completion & Records

Function	Returns	Description
C_ChallengeMode.GetMapPlayerStats(mapID)	durationSec, ...	Personal best
C_ChallengeMode.GetGuildLeaders()	guildLeaders	Guild best runs
C_ChallengeMode.GetCompletionInfo()	mapID, level, time, onTime, keystoneUpgradeLevels, practiceRun, oldOverallDungeonScore, newOverallDungeonScore, IsMapRecord, IsAffixRecord, PrimaryAffix, isEligibleForScore, members	Run completion data
C_ChallengeMode.IsChallengeModeActive()	isActive	In active M+?
C_ChallengeMode.GetDeathCount()	numDeaths, timeLost	Deaths and penalty
C_ChallengeMode.GetActiveChallengeModeLevel()	level	Current key level

Rewards

Function	Returns	Description
C_ChallengeMode.GetChallengeMapInfo(mapID, keystoneLevel)	rewardInfo	Rewards for key level

---

C_MythicPlus — Seasonal M+ Data

Function	Returns	Description
C_MythicPlus.GetCurrentSeason()	seasonID	Current season
C_MythicPlus.GetRunHistory(includePreviousWeeks, includeIncompleteRuns)	runs	Run history
C_MythicPlus.GetRewardLevelFromKeystoneLevel(keystoneLevel)	rewardLevel	Reward item level
C_MythicPlus.GetOwnedKeystoneLevel()	level	Owned key level
C_MythicPlus.GetOwnedKeystoneChallengeMapID()	mapID	Owned key dungeon
C_MythicPlus.GetOwnedKeystoneMapID()	mapID	Owned key map
C_MythicPlus.GetCurrentAffixes()	affixIDs	Current affixes
C_MythicPlus.GetWeeklyChestRewardLevel()	rewardLevel	Vault reward level
C_MythicPlus.GetSeasonBestAffixScoreInfoForMap(mapID)	bestScoreInfo	Best scores by affix
C_MythicPlus.GetSeasonBestForMap(mapID)	intimeInfo, overtimeInfo	Season best runs
C_MythicPlus.GetOverallDungeonScore()	score	Overall M+ rating
C_MythicPlus.RequestCurrentAffixes()	—	Request affix data
C_MythicPlus.RequestMapInfo()	—	Request map data
C_MythicPlus.RequestRewards()	—	Request reward data
C_MythicPlus.IsDungeonScorable(mapID)	isScorable	Awards score?

---

ScenarioInfo — Scenarios & Delves

Function	Returns	Description
C_ScenarioInfo.GetScenarioInfo()	scenarioInfo	Current scenario
C_ScenarioInfo.GetScenarioStepInfo()	stepInfo	Current step
C_ScenarioInfo.GetCriteriaInfo(criteriaIndex)	criteriaInfo	Criteria at index
C_ScenarioInfo.GetCriteriaInfoByStep(stepIndex, criteriaIndex)	criteriaInfo	Step criteria
C_ScenarioInfo.GetScenarioStepByIndex(index)	stepInfo	Step at index

Scenario Info Fields

• name — Scenario name
• currentStage — Current stage
• numStages — Total stages
• flags — Scenario flags
• isComplete — Completed?
• xp — XP reward
• money — Gold reward
• type — Scenario type
• area — Area name
• uiTextureKit — UI texture kit

Step Info Fields

• title — Step title
• description — Step description
• numCriteria — Criteria count
• isComplete — Step complete?
• isBonusObjective — Bonus objective?
• isFinal — Final step?
• weightedProgress — Progress percentage

---

Raid Locks (Saved Instances)

Function	Returns	Description
GetNumSavedInstances()	numInstances	Saved instance count
GetSavedInstanceInfo(index)	name, id, reset, difficulty, locked, extended, instanceIDMostSig, isRaid, maxPlayers, difficultyName, numEncounters, encounterProgress, extendDisabled	Saved instance info
GetSavedInstanceEncounterInfo(index, encounterIndex)	bossName, fileDataID, isKilled, isIneligible	Boss kill status
SetSavedInstanceExtend(index, extend)	—	Extend lockout
GetNumSavedWorldBosses()	count	World boss locks
GetSavedWorldBossInfo(index)	name, id, reset	World boss info
RequestRaidInfo()	—	Request lock data

---

InstanceLeaverInfo — Deserter

Function	Returns	Description
C_InstanceLeaverInfo.GetLeaverInfo()	leaverInfo	Leaver/deserter info
C_InstanceLeaverInfo.HasLeaverPenalty()	hasPenalty	Has deserter?
C_InstanceLeaverInfo.GetLeaverPenaltyTimeRemaining()	seconds	Time remaining

---

C_SeasonInfo — Seasonal Content

Function	Returns	Description
C_SeasonInfo.GetCurrentDisplaySeasonID()	seasonID	Current display season
C_SeasonInfo.GetCurrentSeason()	seasonID	Current season
C_SeasonInfo.GetSeasonInfo(seasonID)	seasonInfo	Season data

---

Common Patterns

List Encounter Journal Bosses

-- Select an instance and list its bosses
EJ_SelectTier(EJ_GetCurrentTier())
EJ_SelectInstance(instanceID)

local index = 1
while true do
    local name, description, encounterID, rootSectionID = EJ_GetEncounterInfoByIndex(index)
    if not name then break end
    print(index, name, "- EncounterID:", encounterID)
    index = index + 1
end

Show M+ Keystone Info

local function ShowKeystoneInfo()
    local level = C_MythicPlus.GetOwnedKeystoneLevel()
    local mapID = C_MythicPlus.GetOwnedKeystoneChallengeMapID()
    if level and mapID then
        local name = C_ChallengeMode.GetMapUIInfo(mapID)
        print("Keystone:", name, "+", level)
    else
        print("No keystone")
    end
    
    local score = C_MythicPlus.GetOverallDungeonScore()
    print("M+ Rating:", score or 0)
end

Check Active M+ Progress

local function ShowMythicPlusProgress()
    if not C_ChallengeMode.IsChallengeModeActive() then
        print("Not in an active M+")
        return
    end
    
    local level = C_ChallengeMode.GetActiveChallengeModeLevel()
    local mapID = C_ChallengeMode.GetActiveChallengeMapID()
    local name = C_ChallengeMode.GetMapUIInfo(mapID)
    local deaths, timeLost = C_ChallengeMode.GetDeathCount()
    
    print(name, "+", level)
    print("Deaths:", deaths, "Time lost:", timeLost, "sec")
end

List Saved Instances

RequestRaidInfo()
-- Wait for UPDATE_INSTANCE_INFO event, then:
local numSaved = GetNumSavedInstances()
for i = 1, numSaved do
    local name, id, reset, difficulty, locked, extended, 
          _, isRaid, maxPlayers, diffName, numEncounters, progress = 
          GetSavedInstanceInfo(i)
    if locked then
        print(name, diffName, progress .. "/" .. numEncounters, 
              "Reset:", SecondsToTime(reset))
    end
end

---

Key Events

Event	Payload	Description
EJ_LOOT_DATA_RECIEVED	itemID	Loot data loaded
EJ_DIFFICULTY_UPDATE	difficultyID	EJ difficulty changed
CHALLENGE_MODE_START	mapID	M+ started
CHALLENGE_MODE_COMPLETED	mapID	M+ completed
CHALLENGE_MODE_RESET	mapID	M+ reset
CHALLENGE_MODE_DEATH_COUNT_UPDATED	—	Death count changed
CHALLENGE_MODE_KEYSTONE_RECEPTABLE_OPEN	—	Font of Power opened
CHALLENGE_MODE_KEYSTONE_SLOTTED	—	Keystone slotted
MYTHIC_PLUS_CURRENT_AFFIX_UPDATE	—	Affixes updated
MYTHIC_PLUS_NEW_WEEKLY_RECORD	mapID	New weekly best
MYTHIC_PLUS_NEW_SEASON_RECORD	mapID	New season best
SCENARIO_UPDATE	—	Scenario state changed
SCENARIO_CRITERIA_UPDATE	—	Criteria updated
SCENARIO_COMPLETED	—	Scenario completed
UPDATE_INSTANCE_INFO	—	Saved instance data
INSTANCE_LOCK_START	—	Lockout acquired
INSTANCE_LOCK_STOP	—	Lockout released
INSTANCE_LOCK_WARNING	—	Lockout warning

---

Gotchas & Restrictions

1. EJ data is async — Loot data loads asynchronously. Wait for EJ_LOOT_DATA_RECIEVED before reading loot.
2. Tier selection matters — EJ functions operate on the currently selected tier. Always set tier first.
3. M+ completion data is temporary — GetCompletionInfo() only returns data immediately after a run.
4. Keystone slotting requires hardware event — Players must manually interact with the Font of Power.
5. Raid lock extensions — SetSavedInstanceExtend() must be called during the lock's active period.
6. Scenario types vary — Delves, island expeditions, and scenarios all use ScenarioInfo with different type flags.
7. M+ rating is per-season — GetOverallDungeonScore() resets each season.
8. RequestRaidInfo() is async — Wait for UPDATE_INSTANCE_INFO before reading saved instances.