API access

Using the API

Authenticate with Authorization: Bearer wos_… or X-Api-Key. Base URL: https://api.whiteoutstats.com/v1.

Limits and freshness

Each key allows 60 requests per minute and 5,000 per day. A Discord account linked to an active Frosty patron gets double that: 120 per minute and 10,000 per day. Exceeding either limit returns 429.

Every counted response includes the remaining allowance:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 42
X-RateLimit-Reset-Minute: 1792000020
X-RateLimit-Limit-Day: 5000
X-RateLimit-Remaining-Day: 3250
X-RateLimit-Reset-Day: 1792022400

The reset values are Unix timestamps. The minute bucket rolls at the start of the next minute. The day bucket rolls at 00:00 UTC. Frosty keys show 120 and 10,000.

GET /v1/usage

/v1/usage returns the same numbers and does not count against either limit. Use it to check before a burst, or to show usage on your own page.

{
  "ok": true,
  "frosty": false,
  "minute": { "limit": 60, "used": 18, "remaining": 42, "resets_at": "2026-10-14T16:27:00Z" },
  "daily": { "limit": 5000, "used": 1750, "remaining": 3250, "resets_at": "2026-10-15T00:00:00Z" }
}

Player and alliance responses may be up to 60 minutes old. Each included section is checked on its own. If a requested section is older than 60 minutes, the request waits up to 90 seconds for an update. Concurrent requests for the same player or alliance share that result. If the wait expires, the last stored copy is returned.

Player

GET /v1/players/{id}?include=base
GET /v1/players/{id}?include=base,heroes,ranks,chief_gear
GET /v1/players/{id}?id_type=uid

id is the in-game chief id by default. Chief ID and internal uid overlap, so the two are not interchangeable.

id_type is optional. Default chief_id (aliases fid, chief) looks up fid only. Pass id_type=uid to look up by internal uid. Unknown IDs return 404. Invalid id_type returns 400.

Wrapper fields: ok, uid, chief_id, id_type, include, fresh, cached_at, age_seconds, player. Extra sections appear only when listed in include.

player (include=base, default):

uid, chief_id, fid, nick_name, kid, power, furnace_level, vip,
x, y, kills, office, online, last_active_at, last_login, avatar_url,
language, shield_endtime, burn_endtime,
alliance: { aid, abbr, name, rank, rank_label, power, count, flag_url, leader_name }

The game no longer sends activity. online, last_active_at, and last_login are leftover values from before that change. They are stale and should not be used.

heroes — arena defence team, including equipped hero gear and exclusive/widget gear:

id, name, level, star, stars, star_label, quality, power, icon, position,
skill_levels: [{ id, level }],
exclusive_gear_level,
exclusive_gear: {
  id, name, level, slot,
  atk_ratio, hp_ratio, def_ratio, power_ratio,
  slg_skill_id, pve_skill_id,
  slg_attr: [{ id, value, label }]
},
gear: [{
  eid, sid, slot, name,
  enhancement_level, refine_level, gear_level,
  quality, quality_key, quality_label, red,
  troop, troop_label
}]

Hero gear is helmet / gloves / armor / boots. enhancement_level is the in-game upgrade (+N). refine_level is mastery forging. red is true at enhancement 101+. exclusive_gear is the hero's exclusive weapon (widget); null if none is on record. Catalog ratios and slg_attr come from the exclusive's wiki row for that hero.

ranks — state standings:

power, power_rank, kills, kills_rank, furnace_level, furnace_rank,
state_transfer_score, state_transfer_rank, labyrinth, labyrinth_rank,
leaderboards: [{ name, value, state_rank }]

chief_gear — chief equipment. When gear is hidden, hidden is true, items is empty, and message explains that.

hidden, message,
items: [{ slot, name, equipid, quality, tier, star, strength_level, score, combat, icon,
          gems: [{ slot, id }] }]

Alliance

GET /v1/alliances/{kid}/{tag}?include=info,roster

Path parameters are state ID and alliance tag (abbr). Tags are case-sensitive. The same tag can exist in more than one state, so kid is required.

alliance (include=info):

aid, name, abbr, kid, power, count, leader_name, leader_uid, leader_chief_id, flag_url, power_rank

members (include=roster):

uid, chief_id, fid, nick_name, power, furnace_level, kills, alliance_rank, alliance_rank_label,
kid, avatar_url, last_active_at, online

State

GET /v1/states?page=1&size=24
GET /v1/states/{kid}
GET /v1/states/{kid}?include=boards&limit=100
GET /v1/states/{kid}/ranks?limit=100
GET /v1/states/{kid}/ranks?board=pet_power&limit=50

state fields:

active_players is chiefs currently on the map (same value as located). active_7d and active_30d are still returned.

kid, name, banner_url, player_count, located, active_players, active_7d, active_30d, alliance_count,
age_days, opened_on, power, avg_power, power_rank, activity_rank, health,
power_gain_7d, tc_pushers_7d,
gov_power, alliance_power, alliance_kills, kills,
hero_power, hero_total, troop_power, building_power, research_power,
hero_no_equip, hero_equip, chief_gear_power, chief_charm_power,
pet_power, island_prosperity, state_transfer_score, labyrinth, master_power,
board_totals: [{ type, key, label, total }]

research_power is also returned as science_power. chief_gear_power is also lord_equip. chief_charm_power is also lord_gem.

Leaderboards are available with include=boards or GET /v1/states/{kid}/ranks. limit is 1–100 (default 100). board is a slug or numeric type:

alliance_power, alliance_kills, personal_power, kills, furnace, rebel_conquest,
single_hero, hero_total, troop_power, building_power, research_power,
hero_no_equip, hero_equip, chief_gear, chief_charm, pet_power,
island_prosperity, state_transfer, labyrinth,
land_of_heroes, cave_of_monsters, charm_mine, research_center, gear_forge, gaia_heart,
master_power

Alliance boards include aid, abbr, name, and score. Player boards include uid, chief_id, nick_name, and score.

Events Frosty

GET /v1/states/{kid}/events

Same calendar as the state page. A Frosty key is required. Any other key receives 403 frosty_required.

Each state is fetched once and kept until 00:00 UTC.

{
  "ok": true,
  "kid": 1,
  "date": "2026-10-05",
  "count": 11,
  "categories": [
    {
      "name": "Events",
      "events": [
        {
          "name": "Hero Rally",
          "category": "Events",
          "when": "28 Sep 00:00 – 11 Oct 24:00",
          "begin_ts": 1759017600,
          "end_ts": 1760227199
        }
      ]
    }
  ]
}

when is the date line shown on the site. begin_ts and end_ts are Unix seconds.

SvS Frosty

GET /v1/states/{kid}/svs

GET /v1/states/{kid}/svs/scores

GET /v1/svs/matchups

Frosty only. Any other key receives 403 frosty_required. This is the same matchup card and live prep board as the state page.

The matchup is this state and its opponent. previous_season is the last stored season for that state, or null. /v1/svs/matchups is every pair in the current season, listed once. Scores are the two state totals and prep days I–V, with In Progress, Available Soon, or Ended. SvS scores are refreshed every 5 minutes. A state with no published score returns 404 scores_unavailable.

{
  "ok": true,
  "season": 22,
  "stage": "armament",
  "bye": false,
  "state": { "kid": 1, "name": null },
  "opponent": { "kid": 39, "name": null },
  "previous_season": 21
}

{
  "ok": true,
  "season": 22,
  "stage": "armament",
  "state": 1,
  "opponent": 39,
  "score": 166483680,
  "opponent_score": 60111200,
  "days": [
    {
      "day": 1,
      "name": "I",
      "status": "In Progress",
      "state_score": 166483680,
      "opponent_score": 60111200,
      "begin_ts": 1791158400,
      "end_ts": 1791244800
    }
  ]
}

Example

curl -sS "https://api.whiteoutstats.com/v1/players/{chief_id}?include=base,heroes,ranks,chief_gear" \
  -H "Authorization: Bearer wos_YOUR_KEY"
curl -sS "https://api.whiteoutstats.com/v1/players/{uid}?id_type=uid&include=base" \
  -H "Authorization: Bearer wos_YOUR_KEY"
curl -sS "https://api.whiteoutstats.com/v1/states/1" \
  -H "Authorization: Bearer wos_YOUR_KEY"
curl -sS "https://api.whiteoutstats.com/v1/states/1/ranks?board=pet_power&limit=20" \
  -H "Authorization: Bearer wos_YOUR_KEY"
curl -sS "https://api.whiteoutstats.com/v1/states/1/events" \
  -H "Authorization: Bearer wos_YOUR_KEY"
curl -sS "https://api.whiteoutstats.com/v1/states/1/svs" \
  -H "Authorization: Bearer wos_YOUR_KEY"
curl -sS "https://api.whiteoutstats.com/v1/states/1/svs/scores" \
  -H "Authorization: Bearer wos_YOUR_KEY"
curl -sS "https://api.whiteoutstats.com/v1/svs/matchups" \
  -H "Authorization: Bearer wos_YOUR_KEY"

401 missing or invalid key. 403 frosty_required on events and SvS without a Frosty key. 404 unknown player, alliance, state, board, or matchup, or scores_unavailable when live scores are not published yet. 429 rate limit exceeded.