---
title: "List Tournaments API"
method: GET
path: "/v2/tournaments"
---

# List Tournaments API

`GET /v2/tournaments`

## Request

- Base URL: `https://api.astrozop.com`
- URL: `https://api.astrozop.com/v2/tournaments`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gamezop/apis/astrozop-apis/docs/v2/tournaments/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists tournaments accessible to your token, optionally filtered by status and game. Rate limit: 10 requests per minute, per token.

## Query parameters

- `status` 'future' | 'live' | 'past'
- `game_code` string
- `lang` string

## Response `200`

List of tournaments accessible to your token. An empty match returns an empty `tournaments` array.

- object
  - `success` boolean
  - `data` object
    - `tournaments` object[]
      - `tournament_id` string: Unique identifier for the tournament.
      - `game` TournamentGame: Details of the game on which the tournament runs.
        - `code` string: Stable game identifier. This is the same `code` value returned by the [All Games API](/publishers/gamezop/types-of-integration/all-games-api).
        - `name` string: Localized game name. Falls back to English if the requested language is not available.
        - `url` string, uri: Playable URL for the game, with `?lang=<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).
      - `title` string: Tournament title.
      - `status` 'future' | 'live' | 'past': Current state of the tournament.
      - `starts_at` string, date-time: Tournament start time (UTC, ISO 8601).
      - `ends_at` string, date-time: Tournament end time (UTC, ISO 8601).
      - `duration_seconds` integer: Tournament duration in seconds.
      - `created_at` string, date-time: Time at which the tournament was created (UTC, ISO 8601).
      - `max_score_attempts` integer: Maximum number of score attempts per player, if a cap was set at creation.

## Other responses

- `400`: Bad Request.
- `401`: Unauthorized.
- `429`: Too Many Requests. Rate limit: 10 requests per minute, per token.

---

[API](https://skmtc.dev/gamezop/apis/astrozop-apis.md) - [All operations](https://skmtc.dev/gamezop/apis/astrozop-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/gamezop/apis/astrozop-apis/revisions/485db86a5145?raw)