---
title: "Top movers in a windowed delta on a leaderboard"
method: POST
path: "/v1/leaderboard.getChanges"
tags: ["leaderboard"]
---

# Top movers in a windowed delta on a leaderboard

`POST /v1/leaderboard.getChanges`

## Request body

- LeaderboardGetChangesRequestBody
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `direction` 'improvements' | 'declines', required — improvements = positive delta, declines = negative delta.
  - `leaderboard` 'apps' | 'awards_given' | 'awards_received' | 'bans' | 'game_bans' | 'vac_bans' | 'foil_badges' | 'normal_badges' | 'badges' | 'playtime' | 'points_given' | 'points_received' | 'steam_sets' | 'xp' | 'valid_playtime', required — Which leaderboard the delta is computed against.
  - `limit` integer — Number of accounts returned per page. Default 100, max 1000.
  - `metric` 'score' | 'rank', required — What to sort by. score = XP/playtime/badges depending on leaderboard. rank = leaderboard position.
  - `offset` integer — Number of accounts to skip, for paging past the first page. Default 0. With topFilter='all' the full leaderboard is pageable, not just the top 1000.
  - `topFilter` '10' | '50' | '100' | '500' | '1000' | 'all' — Restrict to accounts within the top-N of the leaderboard at either endpoint of the window. 'all' = no restriction (default).
  - `window` '24h' | '7d' | '30d' | '90d' | '1y' | 'all', required — Lookback window for the delta. 'all' compares each account's first retained snapshot against its latest, so it widens the delta rather than returning more accounts.

## Response `200`

OK

- LeaderboardGetChangesResponseBody
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `changes` LeaderboardChange[], nullable, required
    - `account` LeaderboardAccount, nullable
      - `animatedAvatar` string, required — The animated avatar of the account
      - `apps` integer, required — The number of apps the account has
      - `avatar` string, required — The avatar hash of the account
      - `avatarFrame` string, required — The avatar frame of the account
      - `awardsGiven` integer, required — The number of awards the account has
      - `awardsReceived` integer, required — The number of awards the account has
      - `background` string, required — The background of the account
      - `badges` integer, required — The number of badges the account has
      - `bans` integer, required — The number of bans
      - `city` LeaderboardCity, nullable
        - `name` string, required — The name of the city
      - `country` LeaderboardCountry, nullable
        - `code` string — The code of the country
        - `name` string, required — The name of the country
      - `createdAt` string, date-time, required — The time the account was created
      - `donated` integer, required — The total of donations the account has
      - `economyBan` string, required — The economy ban of the account
      - `foilBadges` integer, required — The number of foil badges the account has
      - `friends` integer, required — The number of friends the account has
      - `gameBans` integer, required — The number of game bans
      - `level` integer, required — The level of the account
      - `miniBackground` string, required — The mini background of the account
      - `name` string, required — The name of the account
      - `nameEffect` 'none' | 'rainbow' | 'glitch' | 'shadow' | 'neon' | 'retro' | 'stamped' | 'shatter' | 'typewriter' | 'vaporwave' | 'sunken', required — Donator name effect, none when unset or the account no longer holds an entitling role
      - `normalBadges` integer, required — The number of normal badges the account has
      - `playtime` integer, required — The playtime of the account
      - `pointsGiven` integer, required — The number of points the account has
      - `pointsReceived` integer, required — The number of points the account has
      - `privacy` 'public' | 'private' | 'friends_only', required — The privacy of the account
      - `region` LeaderboardRegion, nullable
        - `name` string, required — The name of the region
      - `roles` Role[], nullable, required — The roles of the account
        - `extras` object, nullable, required — Extra data associated with the role
        - `rating` integer, required — The higher the more presedence it has
        - `role` 'user' | 'donator' | 'staff' | 'developer' | 'partner' | 'owner' | 'amethyst' | 'amber' | 'emerald' | 'sapphire' | 'ruby' | 'diamond' | 'contributor' | 'early_supporter' | 'beta' | 'translator' | 'top_100' | 'badge_scout' | 'nitro_booster' | 'astral' | 'nebula', required
      - `state` LeaderboardState, nullable
        - `name` string, required — The name of the state
      - `steamId` string, required — The steam id
      - `steamSetsScore` integer, required — The steam sets score
      - `steamSetsVanity` string, required — The vanity of the account
      - `steamVanity` string, required — The vanity of the account
      - `themeColor` string, nullable, required — Donator profile theme color as #RRGGBB (no alpha), null when unset or the account no longer holds an entitling role
      - `vacBans` integer, required — The number of vac bans
      - `xp` integer, required — The number of xp the account has
    - `accountId` integer, required
    - `latestDate` string, date-time, required
    - `newRank` integer, required
    - `newScore` integer, required
    - `oldRank` integer, required
    - `oldScore` integer, required
    - `rankDelta` integer, required
    - `scoreDelta` integer, required
  - `total` integer, required — Total accounts in this slice, ignoring limit/offset — page until limit+offset reaches it. Reflects the topFilter, since each rank bucket is counted separately.

## Other responses

- `400` — Bad Request
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

[API](https://skmtc.net/steamsets/apis/steamsets-api.md) · [All operations](https://skmtc.net/steamsets/apis/steamsets-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/steamsets/steamsets-api/versions/593d89718daa/schema)