> For the complete documentation index, see [llms.txt](https://docs.thndr.io/integration/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thndr.io/integration/operator-api/active-tournaments.md).

# Active Tournaments

Retrieves the tournaments a given player can join right now.

Use it to show THNDR tournaments in your lobby: what is running, the prizes, and how much time is left.

> **Note:** this endpoint lists only tournaments that are **accepting scores right now**. It does not return upcoming tournaments and it is not a schedule. A tournament appears in the response once it starts and disappears when it ends.

#### Endpoints

**Sandbox**

```
GET https://operator-sandbox.thndr-api.com/v1/active-tournaments/{userId}
```

**Production**

```
GET https://operator.thndr-api.com/v1/active-tournaments/{userId}
```

**Path parameters**

| Parameter | Type   | Description                                   |
| --------- | ------ | --------------------------------------------- |
| `userId`  | string | Player identifier on the Operator's platform. |

The endpoint takes no query parameters. It returns active tournaments across all games available to you.

**Request headers**

```
x-operator-id: your_operator_id
x-api-key: your_api_key
```

**Response**

Returns the requested `userId` and a list of tournaments. Each tournament entry includes:

* A unique tournament identifier (`id`)
* The game identifier (`gameId`), as returned by [Game List](https://docs.thndr.io/integration/operator-api/game-list)
* The start and end of the tournament (`startDate`, `endDate`), ISO 8601 in UTC. Use `endDate` to show the time left.
* The prize currency (`currency`), always `USD`
* The sum of all prizes (`prizePool`), in cents
* The prize tiers (`prizes`), sorted by rank. Each tier has `fromRank`, `toRank` and `amount`. `amount` is the prize for **each** rank in the tier, in cents. Consecutive ranks with the same prize are grouped into one tier.
* The number of players who have entered the tournament so far (`participantsCount`)

```json
{
  "userId": "op-player-8812",
  "tournaments": [
    {
      "id": "0b7c1f6e-2d4a-4c1e-9a55-7f0d8e3b2c11",
      "gameId": "slots",
      "startDate": "2026-10-06T14:00:00.000Z",
      "endDate": "2026-10-06T15:00:00.000Z",
      "currency": "USD",
      "prizePool": 50000,
      "prizes": [
        { "fromRank": 1, "toRank": 1, "amount": 25000 },
        { "fromRank": 2, "toRank": 3, "amount": 7500 },
        { "fromRank": 4, "toRank": 8, "amount": 2000 }
      ],
      "participantsCount": 312
    }
  ]
}
```

In this example, rank 1 wins $250.00, ranks 2 and 3 win $75.00 each, and ranks 4 to 8 win $20.00 each.

**Empty list**

An empty `tournaments` array is a valid response. It means either that no tournament is running for your players right now, or that this player is excluded from tournaments. Do not show a tournament in your lobby in either case.

```json
{
  "userId": "op-player-8812",
  "tournaments": []
}
```

**Response headers**

| Header          | Value                 | Description                                                                                                                    |
| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `Cache-Control` | `private, max-age=30` | How long the response stays fresh, in seconds. Never longer than 30 seconds, and shorter when a listed tournament ends sooner. |
| `Vary`          | `x-operator-id`       | Responses are specific to your operator.                                                                                       |

#### Launching a tournament

The response carries the tournament `id` and the `gameId`, so you can launch the right game from your lobby (see [Launch Game](https://docs.thndr.io/integration/launch-game/standard)). The player joins the tournament from inside the game. Deep links straight into the tournament view are not supported.

#### Polling guidance

Tournaments last a short time, so a lobby needs fresh data, but not on every render. Follow these rules:

* Fetch when the player opens the lobby.
* While the lobby is visible, refresh **no more often than every 30 seconds**. Respect `Cache-Control`: a cached response is valid until its `max-age` runs out.
* Do not poll in the background, or for players who are not looking at the lobby.
* On `429 Too Many Requests`, stop and retry after the number of seconds in the `Retry-After` header.
* On `503 Service Unavailable`, keep the last response you have or hide the tournament section, and retry on the next refresh.

#### Errors

Every error uses the Operator API error shape:<br>

```json
{
  "errors": [
    { "code": "PLAYER_NOT_FOUND", "message": "Player op-player-8812 not found" }
  ]
}
```

`code` is stable and safe to branch on. `message` is for humans, and its wording may change. `errors` always has at least one entry.

| Status | `code`                    | Meaning                                                                                                                                                                                             |
| ------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401    | `NOT_AUTHORIZED`          | The `x-operator-id` or `x-api-key` header is missing or invalid, or the operator is deactivated. Credentials are checked before anything else, so a bad key returns 401 even for an unknown player. |
| 404    | `PLAYER_NOT_FOUND`        | The player is not known to THNDR. This includes players who have never played a THNDR game: they get a 404, not an empty list, until they play their first game.                                    |
| 503    | `TOURNAMENTS_UNAVAILABLE` | Tournaments are temporarily unavailable. The request fails fast (within a few seconds) rather than hanging, so your lobby can carry on without the tournament section.                              |
| 500    | `INTERNAL`                | Unexpected error on our side. It's safe to retry.                                                                                                                                                   |

Examples:

```json
{ "errors": [{ "code": "NOT_AUTHORIZED", "message": "Invalid API Key" }] }
```

```json
{ "errors": [{ "code": "TOURNAMENTS_UNAVAILABLE", "message": "Tournaments are temporarily unavailable" }] }
```

```json
{ "errors": [{ "code": "INTERNAL", "message": "Internal server error" }] }
```
