Top movers in a windowed delta on a leaderboard

POST/v1/leaderboard.getChanges

Authorization

AuthorizationBearer token · headerrequired

Request body

requiredapplication/json

directionstringrequired

improvements = positive delta, declines = negative delta.

Allowed:improvementsdeclines

leaderboardstringrequired

Which leaderboard the delta is computed against.

Allowed:appsawards_givenawards_receivedbansgame_bansvac_bansfoil_badgesnormal_badgesbadgesplaytimepoints_givenpoints_receivedsteam_setsxpvalid_playtime

limitinteger<int32>

Number of accounts returned per page. Default 100, max 1000.

min 1 · max 1000

metricstringrequired

What to sort by. score = XP/playtime/badges depending on leaderboard. rank = leaderboard position.

Allowed:scorerank

offsetinteger<int32>

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.

min 0

topFilterstring

Restrict to accounts within the top-N of the leaderboard at either endpoint of the window. 'all' = no restriction (default).

Allowed:10501005001000all

windowstringrequired

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.

Allowed:24h7d30d90d1yall

Responses

200

changesLeaderboardChange[] | nullrequired

Show properties

Array of LeaderboardChange

accountLeaderboardAccount | null

Show properties

animatedAvatarstringrequired

The animated avatar of the account

appsinteger<int32>required

The number of apps the account has

min 0

avatarstringrequired

The avatar hash of the account

avatarFramestringrequired

The avatar frame of the account

awardsGiveninteger<int32>required

The number of awards the account has

min 0

awardsReceivedinteger<int32>required

The number of awards the account has

min 0

backgroundstringrequired

The background of the account

badgesinteger<int32>required

The number of badges the account has

min 0

bansinteger<int32>required

The number of bans

min 0

cityLeaderboardCity | null

The city of the account

Show properties

namestringrequired

The name of the city

countryLeaderboardCountry | null

The country of the account

Show properties

codestring

The code of the country

namestringrequired

The name of the country

createdAtstring<date-time>required

The time the account was created

donatedinteger<int32>required

The total of donations the account has

min 0

economyBanstringrequired

The economy ban of the account

foilBadgesinteger<int32>required

The number of foil badges the account has

min 0

friendsinteger<int32>required

The number of friends the account has

min 0

gameBansinteger<int32>required

The number of game bans

min 0

levelinteger<int32>required

The level of the account

min 0

miniBackgroundstringrequired

The mini background of the account

namestringrequired

The name of the account

nameEffectstringrequired

Donator name effect, none when unset or the account no longer holds an entitling role

Allowed:nonerainbowglitchshadowneonretrostampedshattertypewritervaporwavesunken

normalBadgesinteger<int32>required

The number of normal badges the account has

min 0

playtimeinteger<int32>required

The playtime of the account

min 0

pointsGiveninteger<int32>required

The number of points the account has

min 0

pointsReceivedinteger<int32>required

The number of points the account has

min 0

privacystringrequired

The privacy of the account

Allowed:publicprivatefriends_only

regionLeaderboardRegion | null

The region of the account

Show properties

namestringrequired

The name of the region

rolesRole[] | nullrequired

The roles of the account

Show properties

Array of Role

extrasobject | nullrequired

Extra data associated with the role

ratinginteger<int32>required

The higher the more presedence it has

rolestringrequired

Allowed:userdonatorstaffdeveloperpartnerowneramethystamberemeraldsapphirerubydiamondcontributorearly_supporterbetatranslatortop_100badge_scoutnitro_boosterastralnebula

stateLeaderboardState | null

The state of the account

Show properties

namestringrequired

The name of the state

steamIdstringrequired

The steam id

steamSetsScoreinteger<int32>required

The steam sets score

min 0

steamSetsVanitystringrequired

The vanity of the account

steamVanitystringrequired

The vanity of the account

themeColorstring | nullrequired

Donator profile theme color as #RRGGBB (no alpha), null when unset or the account no longer holds an entitling role

vacBansinteger<int32>required

The number of vac bans

min 0

xpinteger<int32>required

The number of xp the account has

min 0

accountIdinteger<int32>required

min 0

latestDatestring<date-time>required

newRankinteger<int32>required

min 0

newScoreinteger<int64>required

oldRankinteger<int32>required

min 0

oldScoreinteger<int64>required

rankDeltainteger<int32>required

scoreDeltainteger<int64>required

totalinteger<int32>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.

min 0

400

Bad Request

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties

Array of ErrorDetail

locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"

422

Unprocessable Entity

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties

Array of ErrorDetail

locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"

500

Internal Server Error

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[] | null

Optional list of individual error details

Show properties

Array of ErrorDetail

locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueany

The value at the given location

instancestring<uri>

A URI reference that identifies the specific occurrence of the problem.

statusinteger<int64>

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring<uri>

A URI reference to human-readable documentation for the error.

default: "about:blank"

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Bodyapplication/json

directionstring*improvements = positive delta, declines = negative delta.leaderboardstring*Which leaderboard the delta is computed against.limitintegerNumber of accounts returned per page. Default 100, max 1000.metricstring*What to sort by. score = XP/playtime/badges depending on leaderboard. rank = leaderboard position.offsetintegerNumber 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.topFilterstringRestrict to accounts within the top-N of the leaderboard at either endpoint of the window. 'all' = no restriction (default).windowstring*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.

Request

curl -X POST 'https://api.steamsets.com/v1/leaderboard.getChanges' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "direction": "improvements",
  "leaderboard": "apps",
  "limit": 1,
  "metric": "score",
  "offset": 0,
  "topFilter": "10",
  "window": "24h"
}'

const response = await fetch("https://api.steamsets.com/v1/leaderboard.getChanges", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"direction\": \"improvements\",\n  \"leaderboard\": \"apps\",\n  \"limit\": 1,\n  \"metric\": \"score\",\n  \"offset\": 0,\n  \"topFilter\": \"10\",\n  \"window\": \"24h\"\n}"
});

import requests

response = requests.post(
    "https://api.steamsets.com/v1/leaderboard.getChanges",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"direction\": \"improvements\",\n  \"leaderboard\": \"apps\",\n  \"limit\": 1,\n  \"metric\": \"score\",\n  \"offset\": 0,\n  \"topFilter\": \"10\",\n  \"window\": \"24h\"\n}",
)

Response

{
  "changes": [
    {
      "account": {
        "animatedAvatar": "string",
        "apps": 123456,
        "avatar": "f1a1d2c3d0c9d1e1f2f3f4f5f6f7f8f9",
        "avatarFrame": "string",
        "awardsGiven": 123456,
        "awardsReceived": 123456,
        "background": "string",
        "badges": 123456,
        "bans": 0,
        "city": {
          "name": "Bad Krozingen"
        },
        "country": {
          "code": "DE",
          "name": "Germany"
        },
        "createdAt": "2023-01-01T00:00:00Z",
        "donated": 123456,
        "economyBan": "steam",
        "foilBadges": 123456,
        "friends": 123456,
        "gameBans": 0,
        "level": 123456,
        "miniBackground": "string",
        "name": "steamsets",
        "nameEffect": "rainbow",
        "normalBadges": 123456,
        "playtime": 123456,
        "pointsGiven": 123456,
        "pointsReceived": 123456,
        "privacy": "public",
        "region": {
          "name": "Europe"
        },
        "roles": [
          {
            "extras": {
              "property1": null,
              "property2": null
            },
            "rating": 0,
            "role": "user"
          }
        ],
        "state": {
          "name": "Baden-Wurttemberg"
        },
        "steamId": "76561198842603734",
        "steamSetsScore": 0,
        "steamSetsVanity": "steamsets",
        "steamVanity": "steamsets",
        "themeColor": "#FF5733",
        "vacBans": 0,
        "xp": 123456
      },
      "accountId": 0,
      "latestDate": "2019-08-24T14:15:22Z",
      "newRank": 0,
      "newScore": 0,
      "oldRank": 0,
      "oldScore": 0,
      "rankDelta": 0,
      "scoreDelta": 0
    }
  ],
  "total": 0
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}