> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.gamezop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Live Leaderboard API
> Returns the live leaderboard for a tournament in the `live` state: the leaderboard details, the top entries, and optionally a specific player's rank with one entry above and one below. Rate limit: 1200 requests per minute, per tournament.
Tournaments module is only available with paid plans. [Contact us](https://business.gamezop.com/contact-us/enquire-now) to know more.
## About this API
Returns the live leaderboard for a tournament in progress. This API is only available while the tournament is in the `live` state.
Optionally pass a `puid` to get that player's current rank alongside the top entries.
## `player` object behaviour
| Condition | Behaviour |
| :--------------------------------------- | :---------------------------------------------------------------------- |
| `puid` not passed | `player` object is omitted entirely from the response |
| `puid` passed, player not in leaderboard | `entry` is `null`, `neighbours.above` and `neighbours.below` are `null` |
| Player is at rank 1 | `neighbours.above` is `null` |
| Player is at last rank | `neighbours.below` is `null` |
The rate limit on this API (1200 requests per minute) is counted **per tournament, not per token**. If you fan out to many users, fetch the leaderboard once into your own backend or CDN and serve it from there. Do not proxy every end-user request straight through to this API.
***
## API specification
## OpenAPI
````yaml /openapi-gzp.json get /v2/tournaments/{tournament_id}/leaderboard
openapi: 3.1.0
info:
title: Gamezop APIs
version: 1.0.0
description: >-
OpenAPI specification for Gamezop endpoints including game catalog,
leaderboard metadata, and other integration APIs.
servers:
- url: https://api.gamezop.com
description: Gamezop API
security:
- bearerAuth: []
paths:
/v2/tournaments/{tournament_id}/leaderboard:
get:
summary: Live Leaderboard API
description: >-
Returns the live leaderboard for a tournament in the `live` state: the
leaderboard details, the top entries, and optionally a specific player's
rank with one entry above and one below. Rate limit: 1200 requests per
minute, per tournament.
operationId: getTournamentLeaderboard
parameters:
- name: tournament_id
in: path
required: true
description: The tournament to fetch the live leaderboard for.
schema:
type: string
example: tour_01HZZ2S9GQK6Y3V2S8D7A9F2BC
- name: puid
in: query
required: false
description: >-
The player's unique identifier — the same `puid` value you append to
the game URL when sending that user to the tournament. If provided,
the response includes that player's current rank with one entry
above and one below.
schema:
type: string
example: player_123
- name: limit
in: query
required: false
description: Number of top entries to return. Defaults to 20. Maximum 100.
schema:
type: integer
default: 20
maximum: 100
example: 20
responses:
'200':
description: Live leaderboard for the tournament.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
leaderboard:
type: object
properties:
leaderboard_id:
type: string
description: Stable identifier for this leaderboard.
name:
type: string
description: Human-readable name (e.g. High Score).
description:
type: string
description: Short description of what the leaderboard tracks.
total_players:
type: integer
description: >-
Number of players with at least one valid score in
the tournament.
top:
type: array
description: Top entries of the leaderboard, up to `limit`.
items:
$ref: '#/components/schemas/TournamentLeaderboardEntry'
player:
type: object
description: >-
Present only when `puid` is passed in the request. See
the `player` object behaviour table above.
properties:
entry:
$ref: '#/components/schemas/TournamentLeaderboardEntry'
neighbours:
type: object
properties:
above:
$ref: >-
#/components/schemas/TournamentLeaderboardEntry
description: >-
The entry of the player ranked immediately
above the requested player. The `rank` value
here is that player's own 1-indexed rank (i.e.
the requested player's rank minus 1).
below:
$ref: >-
#/components/schemas/TournamentLeaderboardEntry
description: >-
The entry of the player ranked immediately
below the requested player. The `rank` value
here is that player's own 1-indexed rank (i.e.
the requested player's rank plus 1).
examples:
sample:
summary: Example response (with puid passed)
value:
success: true
data:
leaderboard:
leaderboard_id: lb_B1MfIa4QCg_highscore
name: High Score
description: Top scores across all players for this tournament.
total_players: 19283
top:
- rank: 1
puid: player_987
score: 98200
- rank: 2
puid: player_456
score: 97100
player:
entry:
rank: 42
puid: player_123
score: 75400
neighbours:
above:
rank: 41
puid: player_777
score: 75800
below:
rank: 43
puid: player_555
score: 75100
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
UNAUTHORIZED:
summary: Invalid or missing token
value:
code: UNAUTHORIZED
message: Invalid or missing token.
success: false
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
TOURNAMENT_NOT_ALLOWED:
summary: Token does not have access to this tournament
value:
code: TOURNAMENT_NOT_ALLOWED
message: Your token does not have access to this tournament.
success: false
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
TOURNAMENT_NOT_FOUND:
summary: Tournament ID does not exist
value:
code: TOURNAMENT_NOT_FOUND
message: Tournament ID does not exist.
success: false
'409':
description: Conflict. The tournament is not in the `live` state.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
TOURNAMENT_NOT_LIVE:
summary: Tournament has not started yet
value:
code: TOURNAMENT_NOT_LIVE
message: Tournament has not started yet.
success: false
TOURNAMENT_ENDED:
summary: Tournament is in past state
value:
code: TOURNAMENT_ENDED
message: >-
Tournament is in the past state. Use the Final Results API
instead.
success: false
'429':
description: >-
Too Many Requests. Rate limit: 1200 requests per minute, per
tournament.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
RATE_LIMIT_EXCEEDED:
summary: Too many requests
value:
code: RATE_LIMIT_EXCEEDED
message: >-
Too many requests. Rate limit: 1200 requests per minute,
per tournament.
success: false
components:
schemas:
TournamentLeaderboardEntry:
type: object
properties:
rank:
type: integer
description: 1-indexed rank of the player.
puid:
type: string
description: >-
The player's unique identifier — the same `puid` value appended to
the game URL when sending that user to the tournament.
score:
type: integer
description: The player's best valid score in the tournament.
TournamentErrorResponse:
type: object
properties:
code:
type: string
description: Machine-readable error code identifying the failure.
message:
type: string
description: Human-readable description of the error.
success:
type: boolean
description: Boolean value that is always `false` in error responses.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: UUID
description: >-
You can find the Bearer token for this API under Settings & Admin > API
Tokens within the [Gamezop Business
Dashboard](https://dashboard.gamezop.com).
````