> ## 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.
# List Tournaments API
> Lists tournaments accessible to your token, optionally filtered by status and game. Rate limit: 10 requests per minute, per token.
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 all tournaments accessible to your token. Both query parameters are optional and can be combined to filter the list.
There is no pagination on this API. The response is a finite list, and an empty match returns `"tournaments": []`.
***
## API specification
## OpenAPI
````yaml /openapi-gzp.json get /v2/tournaments
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:
get:
summary: List Tournaments API
description: >-
Lists tournaments accessible to your token, optionally filtered by
status and game. Rate limit: 10 requests per minute, per token.
operationId: listTournaments
parameters:
- name: status
in: query
required: false
description: >-
Filter by tournament state. If omitted, tournaments in all states
are returned.
schema:
type: string
enum:
- future
- live
- past
example: live
- name: game_code
in: query
required: false
description: >-
Filter by a specific game. Use the `code` value from the [All Games
API](/publishers/gamezop/types-of-integration/all-games-api). If
omitted, tournaments for all games are returned.
schema:
type: string
example: B1MfIa4QCg
- name: lang
in: query
required: false
description: >-
ISO 639-1 language code. Defaults to `en`. Localizes `game.name` and
`game.url` in the response, with English as the fallback where a
translation is unavailable.
schema:
type: string
minLength: 2
maxLength: 2
example: en
responses:
'200':
description: >-
List of tournaments accessible to your token. An empty match returns
an empty `tournaments` array.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
tournaments:
type: array
items:
type: object
properties:
tournament_id:
type: string
description: Unique identifier for the tournament.
game:
$ref: '#/components/schemas/TournamentGame'
title:
type: string
description: Tournament title.
status:
type: string
enum:
- future
- live
- past
description: Current state of the tournament.
starts_at:
type: string
format: date-time
description: Tournament start time (UTC, ISO 8601).
ends_at:
type: string
format: date-time
description: Tournament end time (UTC, ISO 8601).
duration_seconds:
type: integer
description: Tournament duration in seconds.
created_at:
type: string
format: date-time
description: >-
Time at which the tournament was created (UTC,
ISO 8601).
max_score_attempts:
type: integer
description: >-
Maximum number of score attempts per player, if
a cap was set at creation.
examples:
sample:
summary: Example response
value:
success: true
data:
tournaments:
- tournament_id: tour_01HZZ2S9GQK6Y3V2S8D7A9F2BC
game:
code: B1MfIa4QCg
name: Bubble Shooter
url: >-
https://www.gamezop.com/g/B1MfIa4QCg?lang=en&tournament_id=tour_01HZZ2S9GQK6Y3V2S8D7A9F2BC
title: Friday 1 Hour Challenge
status: live
starts_at: '2026-06-01T10:00:00Z'
ends_at: '2026-06-01T11:00:00Z'
duration_seconds: 3600
created_at: '2026-05-26T12:30:00Z'
max_score_attempts: 3
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
INVALID_STATUS:
summary: 'status value is not one of: future, live, past'
value:
code: INVALID_STATUS
message: 'status value is not one of: future, live, past.'
success: false
'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
'429':
description: 'Too Many Requests. Rate limit: 10 requests per minute, per token.'
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: 10 requests per minute, per
token.
success: false
components:
schemas:
TournamentGame:
type: object
description: Details of the game on which the tournament runs.
properties:
code:
type: string
description: >-
Stable game identifier. This is the same `code` value returned by
the [All Games
API](/publishers/gamezop/types-of-integration/all-games-api).
name:
type: string
description: >-
Localized game name. Falls back to English if the requested language
is not available.
url:
type: string
format: uri
description: >-
Playable URL for the game, with `?lang=` appended and the
`tournament_id` query parameter already included. When sending users
to the tournament, you must append a `puid` query parameter
identifying each user, for the game to record scores against the
tournament correctly. See [how a tournament
works](/publishers/gamezop/advanced/tournaments#how-a-tournament-works).
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).
````