Steam achievements
Steam achievements API: progress by player and game
Read which achievements a player unlocked in one game, how many there are, and how the player compares with Steam's global unlock percentages.
Updated
curl --fail-with-body \
-H "Authorization: Bearer $WOK_API_KEY" \
"https://woksteamapi.com/v1/games/achievements?steam_id=76561198000000001&appid=252490"Endpoints
A WOK key with all-purpose or Players access. Free Developer keeps its own quota, day and minute limits and the WOK Discord membership rule. Each single read uses one quota unit.
GET /v1/games/achievements | Steam game achievement progress |
|---|---|
GET /v1/apps/achievements/global | Steam global achievement percentages |
POST /v1/games/achievements/batch | Achievements for selected account/game pairs |
Request
Parameters of GET /v1/games/achievements, as published in the OpenAPI description.
| Parameter | Required | Accepted values | Notes |
|---|---|---|---|
steam_id | Required | string | A 17-digit SteamID64. Profile URLs and vanity names are not accepted here. |
appid | Required | integer | Steam AppID of the game. |
Response fields
Fields of a 200 response. A type that includes null means Steam may not publish that value.
| Field | Type | Meaning |
|---|---|---|
steam_id | string | The SteamID64 the response describes. |
appid | integer | Steam AppID of the game. |
game_name | string or null | Game name from Steam; null when it was not returned. |
total | integer | Achievements counted for this game. |
unlocked | integer | Achievements the player has unlocked. |
completion_percent | number or null | Null unless every source achievement validates uniquely and the source count is nonzero. |
achievements | array of object | One entry per achievement Steam returned for this player. |
source | string | Which Steam source produced the data. |
complete | boolean | False when the source list was incomplete or invalid. |
source_achievement_count | integer | How many achievement rows Steam returned. |
What your code should handle
The cases that most often turn into wrong numbers in a product.
One game per call. GET /v1/games/achievements reads one account and one AppID. No method scans achievements across a player's whole library.
Private is not zero. Private or unsupported achievements return 403. They are never returned as zero progress.
Check completeness. completion_percent is null unless every source row is usable. Read complete and source_achievement_count before showing a percentage.
Steam games and playtime APIRust achievements and statsError codes and retries
Status codes
Errors carry a typed code and, where it applies, Retry-After. Respect it on 429 and 503.
| Status | Meaning |
|---|---|
200 | OK |
400 | Invalid request |
401 | Missing or invalid API key |
402 | Quota exhausted or required add-on is not active |
403 | Resource is private or restricted; discord_required means free access requires current WOK Discord membership |
422 | Query or JSON body validation failed |
429 | Rate limit exceeded |
502 | Upstream service failed |
503 | Required upstream capability is unavailable; discord_unavailable means free membership verification should be retried |
Related requests
The same key reads these. Batches use one quota unit per unique account or pair, including cached results.
GET /v1/apps/achievements/global
Steam global achievement percentages.
| Field | Required | Accepted values | Notes |
|---|---|---|---|
appid | Required | integer | Steam AppID of the game. |
POST /v1/games/achievements/batch
Achievements for selected account/game pairs.
| Field | Required | Accepted values | Notes |
|---|---|---|---|
pairs | Required | array of object (1 to 20 entries) | Objects with steam_id and appid. |
include_schema | Optional | boolean (default False) | Adds achievement names, descriptions and icons. |
include_global | Optional | boolean (default False) | Adds Steam's global unlock percentages. |
language | Optional | string: english, russian, german, french, spanish, latam and 39 more (default english) | Language of the schema text; accepted only with include_schema set to true. |
Questions
Do I need a Valve Steam Web API key?
No. WOK holds the Steam Web API key on its servers and makes the Steam call for you. Your server sends a WOK key in the Authorization header.
Can I read every achievement across a player's library in one request?
No. Send explicit account and AppID pairs: one per GET request, or 1 to 20 pairs in POST /v1/games/achievements/batch at one quota unit per unique pair.
How do I get achievement names, descriptions and icons?
Set include_schema to true in the batch, or read GET /v1/apps/schema for the AppID. Definitions include display_name, description, hidden, icon and icon_gray.
Where do global unlock percentages come from?
GET /v1/apps/achievements/global returns Steam's published percentages from 0 to 100 for an AppID. They describe all players, not one player's progress.
Steam account bansSteam friend listsSteam libraries and hoursSteam level and badges