Leaderboards - Get Leaderboard
Get the leaderboard for a specific entity type and statistic.
POST https://titleId.playfabapi.com/Leaderboard/GetLeaderboardRequest Header
| Name | Required | Type | Description |
|---|---|---|---|
| X-EntityToken | True |
string |
This API requires an Entity Session Token, available from the Entity GetEntityToken method. |
Request Body
| Name | Required | Type | Description |
|---|---|---|---|
| LeaderboardName | True |
string |
Name of the leaderboard. |
| PageSize | True |
number |
Maximum number of results to return from the leaderboard. Minimum 1, maximum 1,000. |
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
|
| StartingPosition |
number |
Index position to start from. 1 is beginning of leaderboard. |
|
| Version |
number |
Optional version of the leaderboard, defaults to current version. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
Leaderboard response |
|
| 400 Bad Request |
This is the outer wrapper for all responses with errors |
Security
X-EntityToken
This API requires an Entity Session Token, available from the Entity GetEntityToken method.
Type:
apiKey
In:
header
Definitions
| Name | Description |
|---|---|
|
Api |
The basic wrapper around every failed API response |
|
Entity |
Combined entity type and ID structure which uniquely identifies a single entity. |
|
Entity |
Individual rank of an entity in a leaderboard |
|
Get |
Request to load a leaderboard. |
|
Get |
Leaderboard response |
|
Leaderboard |
|
|
Leaderboard |
|
|
Linked |
ApiErrorWrapper
The basic wrapper around every failed API response
| Name | Type | Description |
|---|---|---|
| code |
integer |
Numerical HTTP code |
| error |
string |
Playfab error code |
| errorCode |
integer |
Numerical PlayFab error code |
| errorDetails |
object |
Detailed description of individual issues with the request object |
| errorMessage |
string |
Description for the PlayFab errorCode |
| status |
string |
String HTTP code |
EntityKey
Combined entity type and ID structure which uniquely identifies a single entity.
| Name | Type | Description |
|---|---|---|
| Id |
string |
Unique ID of the entity. |
| Type |
string |
Entity type. See https://docs.microsoft.com/gaming/playfab/features/data/entities/available-built-in-entity-types |
EntityLeaderboardEntry
Individual rank of an entity in a leaderboard
| Name | Type | Description |
|---|---|---|
| DisplayName |
string |
Entity's display name. |
| Entity |
Entity identifier. |
|
| LastUpdated |
string |
The time at which the last update to the entry was recorded on the server. |
| Metadata |
string |
An opaque blob of data stored on the leaderboard entry. Note that the metadata is not used for ranking purposes. |
| Rank |
number |
Position on the leaderboard. |
| Scores |
string[] |
Scores for the entry. |
GetEntityLeaderboardRequest
Request to load a leaderboard.
| Name | Type | Description |
|---|---|---|
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
| LeaderboardName |
string |
Name of the leaderboard. |
| PageSize |
number |
Maximum number of results to return from the leaderboard. Minimum 1, maximum 1,000. |
| StartingPosition |
number |
Index position to start from. 1 is beginning of leaderboard. |
| Version |
number |
Optional version of the leaderboard, defaults to current version. |
GetEntityLeaderboardResponse
Leaderboard response
| Name | Type | Description |
|---|---|---|
| Columns |
Leaderboard columns describing the sort directions. |
|
| EntryCount |
number |
The number of entries on the leaderboard. |
| Rankings |
Individual entity rankings in the leaderboard, in sorted order by rank. |
|
| Version |
number |
Version of the leaderboard being returned. |
LeaderboardColumn
| Name | Type | Description |
|---|---|---|
| LinkedStatisticColumn |
If the value for this column is sourced from a statistic, details of the linked column. Null if the leaderboard is not linked. |
|
| Name |
string |
A name for the leaderboard column, unique per leaderboard definition. |
| SortDirection |
The sort direction for this column. |
LeaderboardSortDirection
| Name | Type | Description |
|---|---|---|
| Ascending |
string |
|
| Descending |
string |
LinkedStatisticColumn
| Name | Type | Description |
|---|---|---|
| LinkedStatisticColumnName |
string |
The name of the statistic column that this leaderboard column is sourced from. |
| LinkedStatisticName |
string |
The name of the statistic. |
Error Codes
| Name | Code |
|---|---|
| LeaderboardNotFound | 1567 |
| NoLeaderboardForStatistic | 1421 |
| SpecifiedVersionLeaderboardNotFound | 1583 |
| StatisticNotFound | 1195 |