# Event leaderboards

**URL:** https://heroiclabs.com/docs/hiro/godot/event-leaderboards/
**Keywords:** event leaderboards, hiro
**Categories:** hiro, godot, event-leaderboards

---


# Event Leaderboards

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

## Listing Event Leaderboards

You can list all the available event leaderboards to the player by not specifying any categories in the request.

```gdscript
var request = Hiro.EventLeaderboardList.new()

var event_leaderboards = await hiro.eventLeaderboardList(session, request)
print(event_leaderboards)
```

You can filter down the event leaderboards to only include those that belong to at least one of the given categories.

```gdscript
var request = Hiro.EventLeaderboardList.new()
request.categories.append("level_complete")
request.categories.append("race")

var event_leaderboards = await hiro.eventLeaderboardList(session, request)
print(event_leaderboard)
```

By default, the response doesn't include the scores of the event leaderboards. To have the response returning with the scores, set the boolean `with_scores` on the request to true.

```gdscript
var request = Hiro.EventLeaderboardList.new()
request.with_scores = true

var event_leaderboards = await hiro.eventLeaderboardList(session, request)
print(event_leaderboards)
```

## Get an event leaderboard

Get a specified event leaderboard defined for the game.

```gdscript
var request = Hiro.EventLeaderboardGet.new()
request.id = "leaderboard_1"

var event_leaderboard = await hiro.eventLeaderboardGet(session, request)
print(event_leaderboard)

```

## Update event leaderboard record

Update an event leaderboard record for a user.

```gdscript
var request = Hiro.EventLeaderboardUpdate.new()
request.id = "leaderboard_1"
request.score = 100
request.subscore = 10

var event_leaderboard = await hiro.eventLeaderboardUpdate(session, request)
print(event_leaderboard)

```

## Claim event leaderboard reward

Claim an event leaderboard reward for a user.

```gdscript
var request = Hiro.EventLeaderboardClaim.new()
request.id = "leaderboard_1"

var event_leaderboard = await hiro.eventLeaderboardClaim(session, request)
print(event_leaderboard)

```

## Roll a new cohort

Roll a new cohort for the specified event leaderboard.

```gdscript
var request = Hiro.EventLeaderboardRoll.new()
request.id = "leaderboard_1"

var event_leaderboard = await hiro.eventLeaderboardRoll(session, request)
print(event_leaderboard)

```

## Debugging an event leaderboard

You can fill an event leaderboard with dummy users and assign random scores to them for testing purposes.

{{< note "warning" >}}
This is intended for debugging use only.
{{< / note >}}

```gdscript
var fill_request = Hiro.EventLeaderboardDebugFillRequest.new()
fill_request.id = "leaderboard_1"
fill_request.target_count = 50  # Optional target cohort size to fill to, otherwise fill to the max cohort size.

var scores_request = Hiro.EventLeaderboardDebugRandomScoresRequest.new()
scores_request.id = "leaderboard_1"
scores_request.min = "1"
scores_request.max = "100"
scores_request.subscore_min = "1"
scores_request.subscore_max = "100"

# Fills cohort with debug players
var fill_leaderboard = await hiro.eventLeaderboardDebugFill(session, fill_request)
print(fill_leaderboard)

# Sets randomly generated scores between a range for other players (does not change the user's score)
var scores_leaderboard = await hiro.eventLeaderboardDebugRandomScores(session, scores_request)
print(scores_leaderboard)

# Removes user from their current cohort, allowing re-enrollment
var unenroll_request = Hiro.EventLeaderboardDebugUnenrollRequest.new()
unenroll_request.id = "leaderboard_1"

var unenroll_leaderboard = await hiro.eventLeaderboardDebugUnenroll(session, unenroll_request)
print(unenroll_leaderboard)

```