# Event leaderboards

**URL:** https://heroiclabs.com/docs/hiro/python/event-leaderboards/
**Summary:** Manage and interact with event-based leaderboards for player competition.
**Keywords:** event leaderboards, hiro
**Categories:** hiro, python, event-leaderboards

---


# Event Leaderboards

*The Event Leaderboards system enables competitive gameplay through event-specific leaderboards.* Learn more in the [Event Leaderboards concept guide](../../concepts/event-leaderboards/_index.md).

## Overview

Event Leaderboards allow your game to:

* List available event leaderboards.
* Update player scores and standings.
* Claim rewards based on leaderboard performance.
* Manage leaderboard cohorts.

## Before You Start

Ensure you have:

* Unity project configured with Hiro SDK.
* Nakama system integrated ([guide](../getting-started/_index.md)).

## Working with Event Leaderboards

### Listing Event Leaderboards

Retrieve all available leaderboards:

```py
request = EventLeaderboardList()
event_leaderboards = await hiro_client.event_leaderboard_list(request)
print(event_leaderboards)
```

#### Filtering by Categories

Retrieve leaderboards filtered by category:

```py
request = EventLeaderboardList()
request.categories = ["level_complete", "race"]

event_leaderboards = await hiro_client.event_leaderboard_list(request)
print(event_leaderboards)
```

#### Including Scores

Retrieve leaderboards with scores included:

```py
request = EventLeaderboardList()
request.with_scores = True

event_leaderboards = await hiro_client.event_leaderboard_list(request)
print(event_leaderboards)
```

### Getting a Specific Event Leaderboard

Retrieve details for a specific leaderboard:

```py
request = EventLeaderboardGet()
request.id = "leaderboard_1"

event_leaderboard = await hiro_client.event_leaderboard_get(request)
print(event_leaderboard)
```

### Updating Leaderboard Records

Update a player's leaderboard score:

```py
request = EventLeaderboardUpdate()
request.id = "leaderboard_1"
request.score = 100
request.subscore = 10

event_leaderboard = await hiro_client.event_leaderboard_update(request)
print(event_leaderboard)
```

### Claiming Leaderboard Rewards

Claim rewards earned from leaderboard events:

```py
request = EventLeaderboardClaim()
request.id = "leaderboard_1"

event_leaderboard = await hiro_client.event_leaderboard_claim(request)
print(event_leaderboard)
```

### Rolling a New Cohort

Start a new cohort for an event leaderboard:

```py
request = EventLeaderboardRoll()
request.id = "leaderboard_1"

event_leaderboard = await hiro_client.event_leaderboard_roll(request)
print(event_leaderboard)
```

## Debugging Event Leaderboards

> **Warning:** Intended for debugging use only.

Fill event leaderboards with dummy data and assign random scores:

```py
# Filling leaderboard with debug users
fill_request = EventLeaderboardDebugFillRequest()
fill_request.id = "leaderboard_1"
fill_request.target_count = 50  # Optional target cohort size

fill_leaderboard = await hiro_client.event_leaderboard_debug_fill(fill_request)
print(fill_leaderboard)

# Assigning random scores
scores_request = EventLeaderboardDebugRandomScoresRequest()
scores_request.id = "leaderboard_1"
scores_request.min = "1"
scores_request.max = "100"
scores_request.subscore_min = "1"
scores_request.subscore_max = "100"

scores_leaderboard = await hiro_client.event_leaderboard_debug_random_scores(scores_request)
print(scores_leaderboard)

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

unenroll_leaderboard = await hiro_client.event_leaderboard_debug_unenroll(unenroll_request)
print(unenroll_leaderboard)

```

## Next Steps
- [Royal Match King's Cup using Event Leaderboards](../../guides/gameplay-mechanics/event-leaderboard/)