# Event leaderboards

**URL:** https://heroiclabs.com/docs/hiro/typescript/event-leaderboards/
**Keywords:** event leaderboards, hiro
**Categories:** hiro, typescript, 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.

```typescript
const request = new EventLeaderboardList();

const eventLeaderboards = await hiroClient.eventLeaderboardList(session, request);
console.log(eventLeaderboards);
```

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

```typescript
const request = new EventLeaderboardList();
request.categories.push("level_completed");
request.categories.push("race");

const eventLeaderboard = await hiroClient.eventLeaderboardList(session, request);
console.log(eventLeaderboard);
```

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.

```typescript
const request = new EventLeaderboardList();
request.with_scores = true

const eventLeaderboards = await hiroClient.eventLeaderboardList(session, request);
console.log(eventLeaderboards);
```

## Get an event leaderboard

Get a specified event leaderboard defined for the game.

```typescript
const request = new EventLeaderboardGet();
request.id = "leaderboard_1";

const eventLeaderboard = await hiroClient.eventLeaderboardGet(session, request);
console.log(eventLeaderboard);
```

## Update event leaderboard record

Update an event leaderboard record for a user.

```typescript
const request = new EventLeaderboardUpdate();
request.id = "leaderboard_1";
request.score = 100;
request.subscore = 10;

const eventLeaderboard = await hiroClient.eventLeaderboardUpdate(session, request);
console.log(eventLeaderboard);
```

## Claim event leaderboard reward

Claim an event leaderboard reward for a user.

```typescript
const request = new EventLeaderboardClaim();
request.id = "leaderboard_1";

const eventLeaderboard = await hiroClient.eventLeaderboardClaim(session, request);
console.log(eventLeaderboard);
```

## Roll a new cohort

Roll a new cohort for the specified event leaderboard.

```typescript
const request = new EventLeaderboardRoll();
request.id = "leaderboard_1";

const eventLeaderboard = await hiroClient.eventLeaderboardRoll(session, request);
console.log(eventLeaderboard);
```

## 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 >}}

```typescript
const fill_Request = new EventLeaderboardDebugFillRequest();
fill_Request.id = "leaderboard_1";
fill_Request.target_count = 50; // Optional target cohort size to fill to, otherwise fill to the max cohort size.

const scores_Request = new EventLeaderboardDebugRandomScoresRequest();
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
const fill_Leaderboard = await hiroClient.eventLeaderboardDebugFill(session, fill_Request);
console.log(fill_Leaderboard);

// Sets randomly generated scores between a range for other players (does not change the user's score)
const scores_Leaderboard = await hiroClient.eventLeaderboardDebugRandomScores(session, scores_Request);
console.log(scores_Leaderboard);


// Removes user from their current cohort, allowing re-enrollment
const unenroll_Request = new EventLeaderboardDebugUnenrollRequest();
unenroll_Request.id = "leaderboard_1";

const unenroll_Leaderboard = await hiroClient.eventLeaderboardDebugUnenroll(session, unenroll_Request);
console.log(unenroll_Leaderboard);

```