Manage leaderboards from the Admin Portal

Last updated on October 15, 2026

Overview

This article guides you through managing leaderboards in your game from the AccelByte Gaming Services (AGS) Admin Portal or with the AGS CLI, including how to:

• View leaderboard details and players
• Update leaderboard details, cycles, and all-time setting
• Reset leaderboards
• Hide players from leaderboards
• Delete players from leaderboards

Prerequisite

• Access to the AGS Admin Portal.
• To follow the AGS CLI steps, you must have installed the AGS CLI and signed in with an account that has access to these features. See Install and sign in. The examples use a Bash shell.

View leaderboards

Admin Portal

1. In the AGS Admin Portal, go to the game namespace with the leaderboard you want to view.

2. On the sidebar menu, go to Online > Leaderboards. The Leaderboards page appears displaying a list of leaderboards in the game.

3. From the list of leaderboards, find the leaderboard you want to view and click on its code to open its details page. Use the Cycles dropdown to filter the list by specific cycles.

4. On the details page of the leaderboard, you can view the following:

   • Leaderboard details: shows the leaderboard's code, name, statcode (statistic code), cycles, order.
   • Leaderboard data
     • All Players: shows all the players in the leaderboard.
     • Hidden Players: lists players who are part of the leaderboard but are hidden from view in-game.

AGS CLI

1. List the leaderboards in your game namespace. Replace <YourNamespace> with your game namespace:

   ags leaderboard leaderboards list --namespace <YourNamespace>

2. Get the details of a leaderboard. Replace <LeaderboardCode> with its leaderboardCode:

   ags leaderboard leaderboards get --namespace <YourNamespace> --leaderboard-code <LeaderboardCode>

   The output shows the leaderboard's name, statCode, cycleIds, allTime, and descending order.

3. List the players in a leaderboard cycle. Replace <CycleId> with one of the leaderboard's cycleIds:

   ags leaderboard global-rankings list-cycle --namespace <YourNamespace> --leaderboard-code <LeaderboardCode> --cycle-id <CycleId>

   For the all-time cycle, run this command instead:

   ags leaderboard global-rankings list-all-time --namespace <YourNamespace> --leaderboard-code <LeaderboardCode>

4. List the hidden players:

   ags leaderboard visibility list-hidden --namespace <YourNamespace> --leaderboard-code <LeaderboardCode>

Update leaderboard details, cycles, and all-time setting

Admin Portal

1. Go to the details page of the leaderboard you want to update.
2. In the Leaderboard Details section, you can update the leaderboard as follows:
   • Update the leaderboard name.
   • Add or remove cycles from the leaderboard.
   • Enable or disable the All-time cycle setting of the leaderboard.
     • If enabled, the leaderboard updates regularly to show rankings from the entire history of the game.
     • If disabled, the leaderboard displays rankings for a specific period or cycle.
   • Change how the leaderboard displays the order of the ranked players, either by ascending or descending order.
   • Upload or change the icon of the leaderboard.

AGS CLI

1. Save the leaderboard's current settings to a file. Any file name works. This example uses leaderboard.json:

   ags leaderboard leaderboards get --namespace <YourNamespace> --leaderboard-code <LeaderboardCode> --format json > leaderboard.json

2. Edit the fields that you want to change in leaderboard.json:

   • name: the leaderboard name.
   • cycleIds: the cycles of the leaderboard.
   • allTime: true to enable the All-time cycle setting, or false to disable it. Either cycleIds must have at least one cycle, or allTime must be true.
   • descending: true for descending order, or false for ascending.
   • iconURL: the address of an icon image that is already hosted. The Admin Portal uploads the image for you.

3. Update the leaderboard. After @, pass the path to your JSON file:

   ags leaderboard leaderboards update --namespace <YourNamespace> --leaderboard-code <LeaderboardCode> --json @leaderboard.json

   warning

   Removing a cycle from cycleIds, or changing allTime from true to false, deletes the ranking data of that cycle right away. The Admin Portal asks you to confirm before it disables the all-time cycle, but the AGS CLI doesn't.

Reset leaderboard cycles

Resetting a leaderboard cycle resets all ranking data or the points of all players in it. After resetting a leaderboard cycle is reset, it'll be filled again with data when its statistical code configuration is updated.

To reset a leaderboard, follow these steps:

Admin Portal

1. Go to the details page of the leaderboard you want to reset.
2. On the Leaderboard Detail page, click on the Reset Leaderboard button in the Leaderboard Data section. The Reset Leaderboard modal will appear and you are required to select the cycle you want to reset.
3. On the confirmation message, select which cycle of the leaderboard you want to reset and then click Reset. The leaderboard cycle is immediately reset.

AGS CLI

1. Get the details of the leaderboard and note the ID of the cycle to reset from its cycleIds.

2. Reset the cycle. Replace <CycleId> with the cycle ID:

   ags leaderboard global-rankings reset-cycle --namespace <YourNamespace> --leaderboard-code <LeaderboardCode> --cycle-id <CycleId>

Hide players from leaderboards

Admin Portal

1. Go to the details page of the leaderboard.
2. On the details page of the leaderboard, select the leaderboard cycle on where the user ranking you want to delete.
3. Under the All Players tab in the Leaderboard Data section, find the player that you want to delete, click on the Action (...) menu and select Delete.
4. Click on Hide on the confirmation message. The player is immediately hidden from the leaderboard. To view hidden players, go to the Hidden Players tab.

AGS CLI

1. List the players in the leaderboard and note the userId of the player to hide.

2. Hide the player. Replace <UserId> with the player's user ID:

   ags leaderboard visibility set-user-status --namespace <YourNamespace> --leaderboard-code <LeaderboardCode> --user-id <UserId> --json '{"visibility": false}'

   To show the player again, run the same command with "visibility": true.

Delete player ranking data

Deleting a player's ranking data immediately removes them from the leaderboard they're in. They can still rejoin the leaderboard if they manage to gain enough ranking points during the leaderboard cycle.

info

To prevent players from rejoining leaderboards after deleting their ranking data, you can ban them from logging into your game or from matchmaking pools.

To delete a player's ranking data in a leaderboard, follow these steps:

Admin Portal

1. Go to the details page of the leaderboard.
2. On the details page of the leaderboard, select the leaderboard cycle on where the user ranking you want to delete.
3. Under the All Players tab in the Leaderboard Data section, find the player that you want to delete, click on the Action (...) menu and select Delete.
4. Click on Delete on the confirmation message. The player is immediately deleted from the leaderboard cycle.

AGS CLI

1. List the players in the leaderboard cycle and note the userId of the player to delete.

2. Delete the player's ranking data from the cycle. Replace <UserId> with the player's user ID and <CycleId> with the cycle ID:

   ags leaderboard user-rankings reset-cycle --namespace <YourNamespace> --leaderboard-code <LeaderboardCode> --cycle-id <CycleId> --user-id <UserId>

   To delete the player's ranking data from the all-time cycle, run this command instead:

   ags leaderboard user-rankings reset --namespace <YourNamespace> --leaderboard-code <LeaderboardCode> --user-id <UserId>