Working with Xbox Achievements
Fetch achievement lists, track unlock progress, and display gamerscore in your app.
Achievements are core to the Xbox experience. Whether you're building a stats tracker, a completionist tool, or just want to show off rare unlocks, here's how to work with achievement data.
Fetching a Player's Achievements
To get achievements for a specific game, you need the player's XUID and the game's title ID:
curl -X GET "https://xbl.io/api/v2/achievements/player/XUID/TITLE_ID" \
-H "X-Authorization: YOUR_API_KEY"This returns every achievement in the game along with the player's progress. Unlocked achievements include the unlock date and time.
Finding Title IDs
Title IDs aren't always obvious. You can get them from the player's recent games list or search by game name. The recent titles endpoint is usually the easiest approach if you know what games someone plays.
Gamerscore Math
Each achievement has a gamerscore value. Standard achievements are usually 5-100 points. DLC achievements don't count toward the base game total but do add to the player's overall gamerscore.
The player profile endpoint returns total gamerscore directly, so you don't need to sum it yourself unless you're doing per-game breakdowns.
Rare Achievements
Xbox tracks achievement rarity as a percentage of players who've unlocked each one. This data is included in the achievements response. Anything under 10% is considered rare, and under 1% is ultra rare.
Use this to highlight impressive unlocks or build leaderboards around rare achievement hunting.
Handling Large Achievement Lists
Some games have hundreds of achievements (looking at you, Halo MCC). The API paginates results automatically. Check for continuation tokens in the response and make follow-up requests as needed.