# Leaderboards

**URL:** https://heroiclabs.com/docs/hiro/cpp/leaderboards/
**Keywords:** leaderboards, hiro
**Categories:** hiro, cpp, leaderboards

---


# Leaderboards

Read more about the Leaderboards system in Hiro [here](../../concepts/leaderboards/).

{{< note "important" >}}
The methods below require Hiro 1.33 or later. If you are on an earlier version, see [Hiro 1.32 and earlier](#hiro-132-and-earlier).
{{< /note >}}

## Get all leaderboards

List all available leaderboards.

```cpp
Hiro::LeaderboardListRequest request;

hiroClient->leaderboardList(session, request,
    [](const Hiro::LeaderboardList& leaderboardList) {
        for (const auto& leaderboard : leaderboardList.leaderboards) {
            std::cout << "Leaderboard: " << leaderboard.id << '\n';
        }
    },
    [](const Nakama::NError& error) {
        std::cout << Nakama::toString(error.code) << ": " << error.message << '\n';
    }
);
```

Filter by category:

```cpp
Hiro::LeaderboardListRequest request;
request.categories = {"Tournament"};

hiroClient->leaderboardList(session, request, onSuccess, onError);
```

## Get a leaderboard

Get a specified leaderboard by ID.

```cpp
Hiro::LeaderboardGet request;
request.id = "GalacticChampions";

hiroClient->leaderboardGet(session, request,
    [](const Hiro::Leaderboard& leaderboard) {
        std::cout << "Leaderboard: " << leaderboard.id << '\n';
    },
    [](const Nakama::NError& error) {
        std::cout << Nakama::toString(error.code) << ": " << error.message << '\n';
    }
);
```

## Submit a score

Submit a score to a leaderboard.

```cpp
Hiro::LeaderboardUpdate request;
request.id = "GalacticChampions";
request.score = "1500";
request.subscore = "0";

hiroClient->leaderboardUpdate(session, request,
    [](const Hiro::LeaderboardScore& score) {
        std::cout << "Score: " << score.score << '\n';
    },
    [](const Nakama::NError& error) {
        std::cout << Nakama::toString(error.code) << ": " << error.message << '\n';
    }
);
```

## List scores

List scores on a leaderboard. Pass `ownerIds` to retrieve scores for specific owners.

```cpp
Hiro::LeaderboardScoresListRequest request;
request.id = "GalacticChampions";
request.ownerIds = {"userId1", "userId2"};
request.limit = 100;

hiroClient->leaderboardScoresList(session, request,
    [](const Hiro::LeaderboardScoreList& scoreList) {
        for (const auto& score : scoreList.scores) {
            std::cout << score.ownerId << ": " << score.score << '\n';
        }
    },
    [](const Nakama::NError& error) {
        std::cout << Nakama::toString(error.code) << ": " << error.message << '\n';
    }
);
```

Filter by region:

```cpp
Hiro::LeaderboardScoresListRequest request;
request.id = "GalacticChampions";
request.region = "EU";
request.limit = 100;

hiroClient->leaderboardScoresList(session, request, onSuccess, onError);
```

## List scores around owner

List scores centred around a specific owner.

```cpp
Hiro::LeaderboardScoresListAroundOwnerRequest request;
request.id = "GalacticChampions";
request.ownerId = session->user_id;
request.limit = 10;

hiroClient->leaderboardScoresListAroundOwner(session, request,
    [](const Hiro::LeaderboardScoreList& scoreList) {
        for (const auto& score : scoreList.scores) {
            std::cout << score.ownerId << ": " << score.score << '\n';
        }
    },
    [](const Nakama::NError& error) {
        std::cout << Nakama::toString(error.code) << ": " << error.message << '\n';
    }
);
```

## Hiro 1.32 and earlier

Prior to Hiro 1.33, `leaderboardsConfigGet` was the only way to retrieve available leaderboards, returning a `LeaderboardConfigList` with basic configuration data. This method is deprecated in Hiro 1.33 and later. Use `leaderboardList` instead.

```cpp
hiroClient->leaderboardsConfigGet(session,
    [](const Hiro::LeaderboardConfigList& leaderboardConfigList) {
        for (auto it = leaderboardConfigList.leaderboardConfigs.begin(); it != leaderboardConfigList.leaderboardConfigs.end(); it++) {
            std::cout << "Found leaderboard: " << it->id << '\n';
        }
    },
    [](const Nakama::NError& error) {
        std::cout << Nakama::toString(error.code) << ": " << error.message << '\n';
    }
);
```