Documentation

​
​

Development

User Acquisition

Monetization

Industry

Leaderboards API

v1

Supported
​

Leaderboards API

v1

Supported
​
Unity Services Web APIs
​
​
Leaderboards API
  • Introduction
  • General Information
Endpoints
  • Leaderboards

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. Request are limited on a per-player basis to 60 requests per minute which would allow for a sustained request per second.
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.
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
The number of entries to skip when retrieving the leaderboard scores. Defaults to 0

limit

integer
The number of leaderboard scores to return. Defaults to 10

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}

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
The number of entries to skip when retrieving the leaderboard scores. Defaults to 0

limit

integer
The number of leaderboard scores to return. Defaults to 10

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": "string"}

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

{ "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" }}

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
The number of entries either side of the player to retrieve. Defaults to 5.

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
The number of entries either side of the player to retrieve. Defaults to 5.

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

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", "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
No description

versionId

string
No description

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", "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
The number of entries to skip when retrieving the leaderboard scores. Defaults to 0

limit

integer
The number of leaderboard scores to return. Defaults to 10

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

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
The number of entries to skip when retrieving the leaderboard scores. Defaults to 0

limit

integer
The number of leaderboard scores to return. Defaults to 10

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

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" }}
Copyright © 2026 Unity Technologies
LegalPrivacy PolicyCookiesDocumentation Terms of UseDo Not Sell or Share My Personal InformationYour Privacy Choices (Cookie Settings)

"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S and elsewhere (more info here). Other names or brands are trademarks of their respective owners.

Some pages are machine-translated for convenience, and may contain inaccuracies. In the event of conflicting information, the English version is authoritative.