Stability: 3 - Stable


The Leaderboards you can create with Hydra provide realtime ranking of objects in Hydra on any numeric data field. These leaderboards can be maintained for the lifetime of your game or historically for each configured Intervals period. Members of these leaderboards can also be grouped, based on configured data fields. One leaderboard configuration can maintain several regional leaderboards by grouping on a member’s data.region field.

NOTE: Objects that do not have a value for the tracked stat will not be ranked.

NOTE: Hydra leaderboards do not currently support ties. Same score entries will have an arbitrary, but consistent, ranking order.

Leaderboard Types

Basic Leaderboards

The most basic leaderboard is a single lifetime leaderboard ranking members by the configured tracked stat. When that stat is updated, the score on the leaderboard is updated to match. Setting the score to null removes the member from the leaderboard.

Historical Leaderboards

You can associate any configured interval with any leaderboard. When the associated interval rolls over to a new period, a new leaderboard will be created for that period. The previous period’s leaderboard will still be available using the history parameter. Historical leaderboards are currently expired when they are 4 interval periods old.

When a member’s tracked stat is updated the change in the tracked stat value added to the member’s current leaderboard score. In this way, members are ranked based on the total accumulated value of that stat in each time period. Setting the score to null removes the member from the leaderboard in the current time period.

You can configure a leaderboard to use rollups. If rollups are enabled on the associated interval, a historical leaderboard configured to use rollups will pull the historical rollup value for the tracked stat.

NOTE: History for leaderboards start only when this leaderboard is configured. It cannot reach back in time to prior interval periods.

NOTE: Rollups are only available for the following historical leaderboard types: Profiles, Clans, and Clan Members.

See also: Intervals

Grouped Leaderboards

Leaderboard members can be partitioned by a set of group keys into separate leaderboards in order to create more fine grained leaderboards for a given tracked stat. Grouping by data.region for example can configure this type to maintain individual leaderboards for each region.

Setting the score to null removes the member from the leaderboard. Changing a group key value will remove the member from the old leaderboard and add them to the new one.

NOTE: A member that is missing a value for any of the group keys will not be ranked.

Historical Grouped Leaderboards

By grouping members on a leaderboard associated with a interval you get multiple leaderboards (one per partition) maintained for each time period that has elapsed.

Setting the score to null removes the member from the leaderboard in the current time period. Changing a group key value will remove the member from the old partition and add them to the new partition. The value from the old partition will not be transferred, only the current change will be recorded.

See also: Intervals


We provide a number of configurable options for each leaderboard:

Slug :
Human-readable unique identifier for your leaderboard. The slug will be pre-populated for you based on your leaderboard name, but can also be edited at time of creation. A slug cannot be edited after creation.
Name :
The name of your leaderboard.
Description :
(Optional) Full description of the leaderboard to help define exactly what a user needs to do to be ranked.
Tracked Stat :
The full path to the stat on the object that will be used to perform the leaderboard ranking.
Interval :
(Optional) The interval you want to associate this leaderboard with.
Group Keys :
(Optional) A set of full paths to use when partitioning members for ranking on the leaderboard.
Use Rollups :
(Optional) If the historical leaderboard should pull the rollup value of the tracked stat.

Objects that do not have values for the tracked stat will not be included in leaderboards. Any change in the tracked stat or interval will cause the leaderboard to clear and repopulate in an offline process.


Once your Leaderboards are created and users are ranked, you can load them in-game.

We provide several options to customize how you want the leaderboard data returned to you via our Leaderboard Options object:

Sort : enum (Ascending, Descending, Default)
The way the tracked profile stat should be sorted.
Page : int
The specific page of the leaderboard you want to load.
History : string
The historical leaderboard to load. This can be an offset value; 0 for current, 1 for previous etc. It can also be a parsable date string; e.g. 2015-04-24. It can also be the slug for a period if the associated interval type is custom.
Group : list of strings
An ordered list of values to use when fetching a dynamic leaderboard instance.
Fields : list of strings
A list of object data fields to be returned along with each leaderboard entry.

Note: Group Values are not optional when querying on dynamic leaderboards. If the incorrect number of group values are sent a 400 error is returned.

Note: You do not have to provide a value for all of these options. If no value was set, Hydra will use defaults.

Table Of Contents

Previous topic


Next topic