Leaderboards - Create Leaderboard Definition
Creates a new leaderboard definition.
POST https://titleId.playfabapi.com/Leaderboard/CreateLeaderboardDefinitionRequest 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 |
|---|---|---|---|
| Columns | True |
Leaderboard columns describing the sort directions, cannot be changed after creation. A maximum of 5 columns are allowed. |
|
| EntityType | True |
string |
The entity type being represented on the leaderboard. If it doesn't correspond to the PlayFab entity types, use 'external' as the type. |
| Name | True |
string |
A name for the leaderboard, unique per title. |
| SizeLimit | True |
number |
Maximum number of entries on this leaderboard |
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
|
| EventEmissionConfig |
[In Preview]: The configuration for the events emitted by this leaderboard. If not specified, no events will be emitted. |
||
| VersionConfiguration |
The version reset configuration for the leaderboard definition. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK | ||
| 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 |
|
Create |
|
|
Empty |
|
|
Event |
|
|
Leaderboard |
|
|
Leaderboard |
|
|
Leaderboard |
|
|
Leaderboard |
|
|
Leaderboard |
|
|
Linked |
|
|
Reset |
|
|
Version |
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 |
CreateLeaderboardDefinitionRequest
| Name | Type | Description |
|---|---|---|
| Columns |
Leaderboard columns describing the sort directions, cannot be changed after creation. A maximum of 5 columns are allowed. |
|
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
| EntityType |
string |
The entity type being represented on the leaderboard. If it doesn't correspond to the PlayFab entity types, use 'external' as the type. |
| EventEmissionConfig |
[In Preview]: The configuration for the events emitted by this leaderboard. If not specified, no events will be emitted. |
|
| Name |
string |
A name for the leaderboard, unique per title. |
| SizeLimit |
number |
Maximum number of entries on this leaderboard |
| VersionConfiguration |
The version reset configuration for the leaderboard definition. |
EmptyResponse
EventType
| Value | Description |
|---|---|
| None | |
| Telemetry | |
| PlayStream |
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. |
LeaderboardEntityRankOnVersionEndConfig
| Name | Type | Description |
|---|---|---|
| EventType |
The type of event to emit when the leaderboard version end. |
|
| RankLimit |
number |
The maximum number of entity to return on leaderboard version end. Range is 1 to 1000. |
LeaderboardEventEmissionConfig
| Name | Type | Description |
|---|---|---|
| EntityRankOnVersionEndConfig |
This event emits the top ranks of the leaderboard when the leaderboard version end. |
|
| VersionEndConfig |
This event is emitted when the leaderboard version end. |
LeaderboardSortDirection
| Value | Description |
|---|---|
| Descending | |
| Ascending |
LeaderboardVersionEndConfig
| Name | Type | Description |
|---|---|---|
| EventType |
The type of event to emit when the leaderboard version end. |
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. |
ResetInterval
| Value | Description |
|---|---|
| Manual | |
| Hour | |
| Day | |
| Week | |
| Month |
VersionConfiguration
| Name | Type | Description |
|---|---|---|
| MaxQueryableVersions |
number |
The maximum number of versions of this leaderboard/statistic that can be queried. |
| ResetInterval |
Reset interval that statistics or leaderboards will reset on. When using Manual intervalthe reset can only be increased by calling the Increase version API. When using Hour interval the resetwill occur at the start of the next hour UTC time. When using Day interval the reset will occur at thestart of the next day in UTC time. When using the Week interval the reset will occur at the start ofthe next Monday in UTC time. When using Month interval the reset will occur at the start of the nextmonth in UTC time. |
Error Codes
| Name | Code |
|---|---|
| ApiNotEnabledForTitle | 1520 |
| DuplicateColumnNameFound | 1585 |
| DuplicateLinkedStatisticColumnNameFound | 1589 |
| EntityTypeMismatchWithStatDefinition | 1582 |
| ExternalEntityNotAllowedForTier | 1580 |
| InvalidBaseTimeForInterval | 1581 |
| LeaderboardCountLimitExceeded | 1574 |
| LeaderboardNameConflict | 1569 |
| LeaderboardSizeLimitExceeded | 1575 |
| LinkedStatisticColumnMismatch | 1570 |
| LinkedStatisticColumnNotFound | 1586 |
| LinkedStatisticColumnRequired | 1587 |
| LinkingStatsNotAllowedForEntityType | 1573 |
| MaxQueryableVersionsValueNotAllowedForTier | 1591 |
| MultipleLinkedStatisticsNotAllowed | 1588 |
| PlayFabErrorEventNotSupportedForEntityType | 23013 |
| StatDefinitionAlreadyLinkedToLeaderboard | 1572 |
| StatisticNotFound | 1195 |
| VersionConfigurationIsRequired | 23005 |