| name | wow-api-achievements |
| description | Complete reference for WoW Retail Achievement, Statistics, and Achievement Criteria APIs. Covers C_AchievementInfo, global achievement functions (GetAchievementInfo, GetAchievementCriteriaInfo, GetStatistic, GetComparisonStatistic), achievement categories, guild achievements, achievement links, tracked achievements, toast notifications, and achievement-related events. Use when working with achievement tracking, achievement display, statistics, achievement criteria, guild achievements, or achievement completion detection. |
Achievements API (Retail — Patch 12.0.0)
Comprehensive reference for achievements, statistics, and criteria APIs.
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
- Achievement Functions — GetAchievementInfo, criteria, categories
- Statistics — GetStatistic, comparison
- Tracking — Tracked achievements
- Guild Achievements — Guild-specific achievements
Achievement Info
Core Functions
| Function | Returns | Description |
|---|
GetAchievementInfo(achievementID) | id, name, points, completed, month, day, year, description, flags, icon, rewardText, isGuild, wasEarnedByMe, earnedBy, isStatistic | Achievement details |
GetAchievementInfoFromCriteria(criteriaID) | id, name, points, completed, ... | Achievement from criteria |
GetAchievementLink(achievementID) | link | Achievement hyperlink |
GetAchievementNumRewards(achievementID) | numRewards | Reward count |
GetAchievementReward(achievementID, rewardIndex) | text, type, ... | Reward info |
GetPreviousAchievement(achievementID) | prevAchievementID | Achievement chain prev |
GetNextAchievement(achievementID) | nextAchievementID | Achievement chain next |
GetTotalAchievementPoints([isGuild]) | points | Total achievement points |
GetComparisonAchievementPoints() | points | Compared player's points |
SetAchievementSearchString(searchText) | numResults | Search achievements |
GetAchievementSearchSize() | numResults | Search result count |
GetAchievementSearchProgress() | progress | Search progress |
GetFilteredAchievementID(index) | achievementID | Filtered result at index |
Achievement Criteria
| Function | Returns | Description |
|---|
GetAchievementNumCriteria(achievementID) | numCriteria | Number of criteria |
GetAchievementCriteriaInfo(achievementID, criteriaIndex) | criteriaString, criteriaType, completed, quantity, reqQuantity, charName, flags, assetID, quantityString, criteriaID, eligible, duration, elapsed | Criteria details |
GetAchievementCriteriaInfoByID(achievementID, criteriaID) | criteriaString, criteriaType, completed, quantity, reqQuantity, charName, flags, assetID, quantityString, criteriaID, eligible | Criteria by ID |
Achievement Categories
| Function | Returns | Description |
|---|
GetCategoryList() | categoryIDs | All achievement categories |
GetCategoryInfo(categoryID) | title, parentCategoryID, flags | Category info |
GetCategoryNumAchievements(categoryID [, includeAll]) | numAchievements, numCompleted, numIncomplete | Category stats |
GetAchievementCategory(achievementID) | categoryID | Achievement's category |
Achievement Comparison (Inspect)
| Function | Returns | Description |
|---|
GetComparisonStatistic(achievementID) | value | Compared player's statistic |
ClearAchievementComparisonUnit() | — | Clear comparison |
SetAchievementComparisonUnit(unit) | success | Set comparison target |
Statistics
| Function | Returns | Description |
|---|
GetStatistic(achievementID) | value | Statistic value (string) |
GetStatisticsCategoryList() | categoryIDs | Statistic categories |
GetCategoryAchievementPoints(categoryID, includeAll) | points, completedPoints | Category points |
Achievement Tracking
| Function | Returns | Description |
|---|
GetTrackedAchievements() | ... (achievementIDs) | All tracked achievements |
GetNumTrackedAchievements() | numTracked | Tracked count |
AddTrackedAchievement(achievementID) | — | Track achievement |
RemoveTrackedAchievement(achievementID) | — | Untrack achievement |
IsTrackedAchievement(achievementID) | isTracked | Is tracked? |
Common Patterns
Check Achievement Completion
local function IsAchievementDone(achievementID)
local _, _, _, completed = GetAchievementInfo(achievementID)
return completed
end
Display Achievement Criteria Progress
local function PrintCriteriaProgress(achievementID)
local _, name = GetAchievementInfo(achievementID)
print("Achievement:", name)
local numCriteria = GetAchievementNumCriteria(achievementID)
for i = 1, numCriteria do
local criteriaString, _, completed, quantity, reqQuantity =
GetAchievementCriteriaInfo(achievementID, i)
local status = completed and "DONE" or (quantity .. "/" .. reqQuantity)
print(" ", criteriaString, status)
end
end
Search Achievements
local function SearchAchievements(text)
local numResults = SetAchievementSearchString(text)
local results = {}
for i = 1, GetAchievementSearchSize() do
local achievementID = GetFilteredAchievementID(i)
local _, name, points, completed = GetAchievementInfo(achievementID)
table.insert(results, {id = achievementID, name = name, points = points, done = completed})
end
return results
end
Key Events
| Event | Payload | Description |
|---|
ACHIEVEMENT_EARNED | achievementID, alreadyEarned | Achievement completed |
CRITERIA_EARNED | achievementID, criteriaString | Criteria completed |
CRITERIA_UPDATE | — | Criteria progress updated |
CRITERIA_COMPLETE | — | All criteria complete |
TRACKED_ACHIEVEMENT_LIST_CHANGED | achievementID, added | Tracking changed |
TRACKED_ACHIEVEMENT_UPDATE | achievementID | Tracked achievement updated |
ACHIEVEMENT_SEARCH_UPDATED | — | Search results ready |
INSPECT_ACHIEVEMENT_READY | guid | Inspect achievement data ready |
RECEIVED_ACHIEVEMENT_MEMBER_LIST | achievementID | Member list received |
Gotchas & Restrictions
- GetAchievementInfo returns 15 values — Destructure carefully. The
completed boolean is the 4th return.
- Guild vs personal — Pass
true as isGuild to GetCategoryNumAchievements() for guild achievements.
- Statistics are strings —
GetStatistic() returns a formatted string, not a number. Parse with tonumber() if needed.
- Criteria index is 1-based — Criteria indices start at 1, up to
GetAchievementNumCriteria().
- Achievement chains — Some achievements are chained (10/25/50 kills etc.). Use
GetPreviousAchievement()/GetNextAchievement().
- Search is async —
SetAchievementSearchString() may not return all results immediately. Wait for ACHIEVEMENT_SEARCH_UPDATED.
- Tracking limit — There's a maximum number of tracked achievements.
- Inspect data — Achievement comparison requires
SetAchievementComparisonUnit() and waiting for INSPECT_ACHIEVEMENT_READY.
