Documentation

Leaderboards API

Leaderboards API

Leaderboards API

Introduction

This is the API specification for the Unity Leaderboards service that enables game developers to store, sort, and rank scores for their games.

General Information

A leaderboard score can be created through this API. In addition, player scores can be retrieved (either as a set of leaderboard entries or for a particular player), both for the active leaderboard version and any archived read-only versions, and a list of versions can be retrieved.

Rate Limits

The API has rate limiting in place. Requests are limited on a per-player basis to 60 requests per minute.
The API responds with a 
429
HTTP status code if the rate limit is exceeded.
It will also respond with a 
Retry-After
header to be used in conjunction with a client's retry logic. The value is the number of seconds until a request for the given player will be accepted.

Leaderboard Configuration

Leaderboard settings such as tiers, buckets, sort order (ascending or descending), reset schedule, and update type (keepBest, keepLatest, or aggregate) are configured through the Leaderboards Admin API. The update type determines how Add Player Score handles new scores for a player who already has a score.
Download OpenAPI specification:

Get Scores

Get list of scores and ranks for the specified leaderboard, with specified pagination.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Scores"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

Query parameters for "Get Scores"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

offset

integer
default: 0
The number of entries to skip when retrieving the leaderboard scores.

limit

integer
default: 10
The number of leaderboard scores to return.

HTTP response status codes for "Get Scores":

Code samples for "Get Scores":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/scores"

Response example

{ "offset": 0, "limit": 10, "total": 1, "results": [ { "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" } } ]}

Get Scores By Tier

Get list of scores and ranks for the specified leaderboard, within the specified tier, with specified pagination.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Scores By Tier"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

tierId

string
required
example: gold
ID of the leaderboard tier.

Query parameters for "Get Scores By Tier"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

offset

integer
default: 0
The number of entries to skip when retrieving the leaderboard scores.

limit

integer
default: 10
The number of leaderboard scores to return.

HTTP response status codes for "Get Scores By Tier":

Code samples for "Get Scores By Tier":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/tiers/{tierId}/scores"

Response example

{ "tier": "gold", "offset": 0, "limit": 10, "total": 1, "results": [ { "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" } } ]}

Get Scores By PlayerIds

Get list of scores and ranks for the specified leaderboard, with specified playerIds.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Scores By PlayerIds"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

Query parameters for "Get Scores By PlayerIds"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

Request body for "Get Scores By PlayerIds"

Media Type:
application/json

playerIds

array[string]
example: ["5drhidte8XgD4658j2eHtSljIAzA","GZWIdLM4I1vFvv1VGhqqDKNPK06b"]
No description

HTTP response status codes for "Get Scores By PlayerIds":

Code samples for "Get Scores By PlayerIds":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "playerIds": [ "5drhidte8XgD4658j2eHtSljIAzA", "GZWIdLM4I1vFvv1VGhqqDKNPK06b" ]}' \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/scores/players"

Response example

{ "results": [ { "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" } } ], "entriesNotFoundForPlayerIds": [ "GZWIdLM4I1vFvv1VGhqqDKNPK06b" ]}

Get Scores By PlayerIds for Archived Leaderboard

Get list of scores and ranks for an archived leaderboard, with specified playerIds.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Scores By PlayerIds for Archived Leaderboard"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

versionId

string
required
example: 20220517135053019266622
ID of the leaderboard version

Query parameters for "Get Scores By PlayerIds for Archived Leaderboard"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

Request body for "Get Scores By PlayerIds for Archived Leaderboard"

Media Type:
application/json

playerIds

array[string]
example: ["5drhidte8XgD4658j2eHtSljIAzA","GZWIdLM4I1vFvv1VGhqqDKNPK06b"]
No description

HTTP response status codes for "Get Scores By PlayerIds for Archived Leaderboard":

Code samples for "Get Scores By PlayerIds for Archived Leaderboard":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "playerIds": [ "5drhidte8XgD4658j2eHtSljIAzA", "GZWIdLM4I1vFvv1VGhqqDKNPK06b" ]}' \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/versions/{versionId}/scores/players"

Response example

{ "version": { "id": "20230213175322850781977", "start": "2024-01-01T00:00:00Z", "end": "2024-01-01T00:00:00Z" }, "results": [ { "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" } } ], "entriesNotFoundForPlayerIds": [ "GZWIdLM4I1vFvv1VGhqqDKNPK06b" ]}

Get Player Range

Get the list of neighbouring players for the specified player Id.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Player Range"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
ID of the player

Query parameters for "Get Player Range"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

rangeLimit

integer
default: 5
The number of entries on each side of the player to retrieve.

HTTP response status codes for "Get Player Range":

Code samples for "Get Player Range":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/scores/players/{playerId}/range"

Response example

{ "results": [ { "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" } } ]}

Get Player Range for Archived Leaderboard

Get the list of neighbouring players for the specified player Id for an archived Leaderboard.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Player Range for Archived Leaderboard"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

versionId

string
required
example: 20220517135053019266622
ID of the leaderboard version

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
ID of the player

Query parameters for "Get Player Range for Archived Leaderboard"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

rangeLimit

integer
default: 5
The number of entries on each side of the player to retrieve.

HTTP response status codes for "Get Player Range for Archived Leaderboard":

Code samples for "Get Player Range for Archived Leaderboard":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/versions/{versionId}/scores/players/{playerId}/range"

Response example

{ "version": { "id": "20230213175322850781977", "start": "2024-01-01T00:00:00Z", "end": "2024-01-01T00:00:00Z" }, "results": [ { "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" } } ]}

Get Player Score

Get score and rank for the specified player in the specified leaderboard.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Player Score"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
ID of the player

Query parameters for "Get Player Score"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

HTTP response status codes for "Get Player Score":

Code samples for "Get Player Score":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/scores/players/{playerId}"

Response example

{ "updatedTime": "2024-01-01T00:00:00Z", "bucketId": "string", "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" }}

Add Player Score

Add score for the specified player to the specified leaderboard.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Add Player Score"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
ID of the player

Request body for "Add Player Score"

Media Type:
application/json

score

number
required
example: 120.3
No description

metadata

object
Arbitrary JSON object to store with the score entry.

versionId

string
Optional version ID for optimistic locking. If provided, the request is rejected if this does not match the current live version of the leaderboard.

HTTP response status codes for "Add Player Score":

Code samples for "Add Player Score":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "score": 120.3, "metadata": {}, "versionId": "string"}' \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/scores/players/{playerId}"

Response example

{ "updatedTime": "2024-01-01T00:00:00Z", "bucketId": "string", "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" }}

Get Archived Versions

Get list of archived leaderboard versions for the specified leaderboard, with specified pagination.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Archived Versions"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

Query parameters for "Get Archived Versions"

limit

integer
The number of leaderboard versions to return.

HTTP response status codes for "Get Archived Versions":

Code samples for "Get Archived Versions":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/versions"

Response example

{ "leaderboardId": "my-leaderboard", "nextReset": "2024-01-01T00:00:00Z", "versionId": "20230213175322850781990", "totalArchivedVersions": 3, "results": [ { "id": "20230213175322850781977", "start": "2024-01-01T00:00:00Z", "end": "2024-01-01T00:00:00Z" } ]}

Get Archived Version Scores

Get list of scores and ranks for the specified archived leaderboard version, with specified pagination.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Archived Version Scores"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

versionId

string
required
example: 20220517135053019266622
ID of the leaderboard version

Query parameters for "Get Archived Version Scores"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

offset

integer
default: 0
The number of entries to skip when retrieving the leaderboard scores.

limit

integer
default: 10
The number of leaderboard scores to return.

HTTP response status codes for "Get Archived Version Scores":

Code samples for "Get Archived Version Scores":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/versions/{versionId}/scores"

Response example

{ "version": { "id": "20230213175322850781977", "start": "2024-01-01T00:00:00Z", "end": "2024-01-01T00:00:00Z" }, "offset": 0, "limit": 10, "total": 1, "results": [ { "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" } } ]}

Get Archived Version Scores By Tier

Get list of scores and ranks for the specified archived leaderboard version, within the specified tier, with specified pagination.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Archived Version Scores By Tier"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

versionId

string
required
example: 20220517135053019266622
ID of the leaderboard version

tierId

string
required
example: gold
ID of the leaderboard tier.

Query parameters for "Get Archived Version Scores By Tier"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

offset

integer
default: 0
The number of entries to skip when retrieving the leaderboard scores.

limit

integer
default: 10
The number of leaderboard scores to return.

HTTP response status codes for "Get Archived Version Scores By Tier":

Code samples for "Get Archived Version Scores By Tier":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/versions/{versionId}/tiers/{tierId}/scores"

Response example

{ "tier": "gold", "version": { "id": "20230213175322850781977", "start": "2024-01-01T00:00:00Z", "end": "2024-01-01T00:00:00Z" }, "offset": 0, "limit": 10, "total": 1, "results": [ { "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" } } ]}

Get Archived Version Player Score

Get score and rank for the specified player in the specified archived leaderboard version.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Archived Version Player Score"

projectId

string
required
The project's Project ID

leaderboardId

string
required
example: my-leaderboard
ID of the leaderboard

versionId

string
required
example: 20220517135053019266622
ID of the leaderboard version

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
ID of the player

Query parameters for "Get Archived Version Player Score"

includeMetadata

boolean
example: false
True/false to determine whether to include metadata.

HTTP response status codes for "Get Archived Version Player Score":

Code samples for "Get Archived Version Player Score":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://leaderboards.services.api.unity.com/v1/projects/{projectId}/leaderboards/{leaderboardId}/versions/{versionId}/scores/players/{playerId}"

Response example

{ "version": { "id": "20230213175322850781977", "start": "2024-01-01T00:00:00Z", "end": "2024-01-01T00:00:00Z" }, "playerId": "5drhidte8XgD4658j2eHtSljIAzA", "playerName": "Jane Doe", "rank": 42, "score": 120.3, "tier": "gold", "metadata": { "team": "red" }}