> ## 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.
# Final Results API
> Returns the final ranked results after a tournament has ended, capped at the top 10,000 entries. Rate limit: 24 requests per 24 hours, 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 final ranked results after a tournament has ended. Results are only available once processing is complete — if you call this API too early, you will receive a `RESULTS_NOT_READY` error with a `Retry-After` header (approximately 30 seconds).
The results list is capped at the top 10,000 entries.
The rate limit on this API (24 requests per 24 hours) is counted **per tournament, not per token**. Fetch the results once into your own backend and serve them from there.
***
## API specification
## OpenAPI
````yaml /openapi-gzp.json get /v2/tournaments/{tournament_id}/results
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}/results:
get:
summary: Final Results API
description: >-
Returns the final ranked results after a tournament has ended, capped at
the top 10,000 entries. Rate limit: 24 requests per 24 hours, per
tournament.
operationId: getTournamentResults
parameters:
- name: tournament_id
in: path
required: true
description: The tournament to fetch final results for.
schema:
type: string
example: tour_01HZZ2S9GQK6Y3V2S8D7A9F2BC
responses:
'200':
description: Final ranked results for the tournament.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
results:
type: object
properties:
total_players:
type: integer
description: >-
Number of players with at least one valid score in
the tournament.
entries:
type: array
description: Final ranked entries, capped at the top 10,000.
items:
$ref: '#/components/schemas/TournamentLeaderboardEntry'
examples:
sample:
summary: Example response
value:
success: true
data:
results:
total_players: 18234
entries:
- rank: 1
puid: player_987
score: 98200
- rank: 2
puid: player_456
score: 97100
'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 has not ended, or results are still being
processed.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
TOURNAMENT_NOT_STARTED:
summary: Tournament has not started yet
value:
code: TOURNAMENT_NOT_STARTED
message: Tournament has not started yet.
success: false
TOURNAMENT_STILL_LIVE:
summary: Tournament is still running
value:
code: TOURNAMENT_STILL_LIVE
message: >-
Tournament is still running. Use the Live Leaderboard API
instead.
success: false
RESULTS_NOT_READY:
summary: >-
Results are being processed; a Retry-After header is
included
value:
code: RESULTS_NOT_READY
message: >-
Results are being processed. Please retry after the
duration indicated in the Retry-After header.
success: false
headers:
Retry-After:
description: >-
Included with `RESULTS_NOT_READY`. Number of seconds after which
to retry the request (approximately 30 seconds).
schema:
type: integer
'429':
description: >-
Too Many Requests. Rate limit: 24 requests per 24 hours, 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: 24 requests per 24 hours,
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).
````