List Current Tournaments

Get all current tournaments including scheduled, started, and finished tournaments

Overview

Retrieve information about all currently visible tournaments on Lichess. This endpoint returns scheduled tournaments, ongoing tournaments, and recently finished tournaments.

Endpoint

GET /api/tournament

curl https://lichess.org/api/tournament

Response Format

Returns a JSON object with three arrays:

created · array

Array of scheduled tournaments that haven’t started yet

Show Tournament Object

id · string · required

8-character tournament ID

name · string · required

Tournament name

status · integer · required

Tournament status: 10 (created), 20 (started), 30 (finished)

createdBy · string · required

User ID of tournament creator

startsAt · integer · required

Tournament start timestamp in milliseconds

finishesAt · integer · required

Tournament end timestamp in milliseconds

nbPlayers · integer · required

Number of players who joined

variant · object · required

Chess variant information

Show Variant

key · string

Variant key (e.g., “standard”, “chess960”, “crazyhouse”)

name · string

Human-readable variant name

clock · object · required

Time control settings

Show Clock

limit · integer

Initial time in seconds

increment · integer

Increment per move in seconds

minutes · integer · required

Tournament duration in minutes

rated · boolean

Whether the tournament is rated

perf · object

Performance type information

Show Performance Type

key · string

Performance type key (e.g., “bullet”, “blitz”, “rapid”, “classical”)

name · string

Human-readable performance type name

position · object

Starting position (for thematic tournaments)

Show Position

fen · string

FEN notation of starting position

name · string

Opening name

teamBattle · object

Team battle information (if applicable)

Show Team Battle

teams · array

Array of team IDs participating in the battle

nbLeaders · integer

Number of leaders per team

schedule · object

Scheduling information for official tournaments

Show Schedule

freq · string

Frequency: “hourly”, “daily”, “weekly”, “monthly”, “yearly”, “shield”, “marathon”, “unique”

speed · string

Speed category: “ultraBullet”, “bullet”, “blitz”, “rapid”, “classical”

started · array

Array of tournaments currently in progress

finished · array

Array of recently finished notable tournaments

Example Response

{
  "created": [
    {
      "id": "QITRjufu",
      "createdBy": "lichess",
      "startsAt": 1709740800000,
      "name": "Hourly Bullet Arena",
      "clock": {
        "limit": 60,
        "increment": 0
      },
      "minutes": 30,
      "status": 10,
      "nbPlayers": 45,
      "variant": {
        "key": "standard",
        "name": "Standard"
      },
      "rated": true,
      "perf": {
        "key": "bullet",
        "name": "Bullet"
      },
      "finishesAt": 1709742600000,
      "schedule": {
        "freq": "hourly",
        "speed": "bullet"
      }
    }
  ],
  "started": [
    {
      "id": "Xg7K4bTy",
      "createdBy": "lichess",
      "startsAt": 1709738400000,
      "name": "Hourly Blitz Arena",
      "clock": {
        "limit": 180,
        "increment": 0
      },
      "minutes": 45,
      "status": 20,
      "nbPlayers": 234,
      "variant": {
        "key": "standard",
        "name": "Standard"
      },
      "rated": true,
      "perf": {
        "key": "blitz",
        "name": "Blitz"
      },
      "finishesAt": 1709741100000
    }
  ],
  "finished": [
    {
      "id": "Ab2Cd3Ef",
      "createdBy": "lichess",
      "startsAt": 1709732400000,
      "name": "Daily Classical Arena",
      "clock": {
        "limit": 900,
        "increment": 10
      },
      "minutes": 180,
      "status": 30,
      "nbPlayers": 567,
      "variant": {
        "key": "standard",
        "name": "Standard"
      },
      "rated": true,
      "perf": {
        "key": "classical",
        "name": "Classical"
      },
      "finishesAt": 1709743200000,
      "winnerId": "some_user"
    }
  ]
}

Tournament Status Values

• 10 - Created (scheduled, not started)
• 20 - Started (in progress)
• 30 - Finished

Rate Limits

This endpoint is subject to standard rate limits. No authentication is required.

Related Endpoints

• Get Tournament Details - Get full details of a specific tournament
• Create Tournament - Create a new arena tournament
• Join Tournament - Join an existing tournament

Source Code Reference

Implementation can be found in:

• app/controllers/Api.scala:146 - currentTournaments method
• app/controllers/Tournament.scala:146 - Tournament API handling