Steam level and badges
Steam level API: level, XP and badges
Read an account's Steam level on its own, or its badges together with XP and the XP still needed for the next level.
Updated
curl --fail-with-body \
-H "Authorization: Bearer $WOK_API_KEY" \
"https://woksteamapi.com/v1/badges?steam_id=76561198000000001"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/badges | Steam badges, account XP and level |
|---|---|
GET /v1/steam-level | Steam account level |
Request
Parameters of GET /v1/badges, as published in the OpenAPI description.
| Parameter | Required | Accepted values | Notes |
|---|---|---|---|
steam_id | Required | string | A 17-digit SteamID64. |
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. |
badges | array of object | Badges the account publishes. |
badges.badgeid | integer or null | Steam's badge identifier. |
badges.level | integer or null | Level of that badge. |
badges.completion_time | integer or null | When the badge was completed, as Steam reports it. |
badges.xp | integer or null | XP the badge gives. |
badges.scarcity | integer or null | How many accounts hold the badge, as Steam reports it. |
badges.appid | integer or null | AppID for a game badge; null for other badges. |
badges.communityitemid | integer or null | Steam's community item identifier for the badge. |
badges.border_color | integer or null | Steam's border colour value for the badge. |
count | integer or null | Number of entries returned. |
player_xp | integer or null | Total account XP; null when Steam did not return it. |
player_level | integer or null | Account level from the badge data. |
player_xp_needed_to_level_up | integer or null | XP still needed for the next level. |
player_xp_needed_current_level | integer or null | XP at which the current level started. |
complete | boolean | False together with status=unknown separates unavailable data from an empty badge list. |
status | string: available, unknown | unknown when badge data was unavailable. |
source | string | Which Steam source produced the data. |
What your code should handle
The cases that most often turn into wrong numbers in a product.
Level alone is one call. GET /v1/steam-level returns the account level. A level that is hidden or absent at Steam returns 403 steam_level_unavailable.
Badges carry the XP. GET /v1/badges returns badges, their count, player_xp, player_level and the XP needed for the next level.
Null means unknown. Missing values stay null. status=unknown with complete=false means the data was unavailable, not that the account has no badges.
Free Steam level checkerSteam profile APISteam games and playtime API
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/steam-level
Steam account level.
| Field | Required | Accepted values | Notes |
|---|---|---|---|
steam_id | Required | string | A 17-digit SteamID64. Profile URLs and vanity names are not accepted here. |
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.
How do I get the XP needed for the next level?
Read player_xp_needed_to_level_up from GET /v1/badges. The level-only endpoint does not return XP.
What if the level is hidden?
GET /v1/steam-level returns 403 with the code steam_level_unavailable. Do not show it as level 0.
How fresh is badge data?
A cold read makes one Steam badge lookup and the result is cached for 300 seconds.
Steam account bansSteam friend listsSteam libraries and hoursSteam achievements