List Current Tournaments

Overview

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

Endpoint

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

Response Format

Returns a JSON object with three arrays:

array

Array of scheduled tournaments that haven’t started yet

Show Tournament Object

string

required

8-character tournament ID

string

required

Tournament name

integer

required

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

string

required

User ID of tournament creator

integer

required

Tournament start timestamp in milliseconds

integer

required

Tournament end timestamp in milliseconds

integer

required

Number of players who joined

object

required

Chess variant information

Show Variant

string

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

string

Human-readable variant name

object

required

Time control settings

Show Clock

integer

Initial time in seconds

integer

Increment per move in seconds

integer

required

Tournament duration in minutes

boolean

Whether the tournament is rated

object

Performance type information

Show Performance Type

string

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

string

Human-readable performance type name

object

Starting position (for thematic tournaments)

Show Position

string

FEN notation of starting position

string

Opening name

object

Team battle information (if applicable)

Show Team Battle

array

Array of team IDs participating in the battle

integer

Number of leaders per team

object

Scheduling information for official tournaments

Show Schedule

string

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

string

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

array

Array of tournaments currently in progress

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.

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

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

List Current Tournaments

Overview

Endpoint

Response Format

Example Response

Tournament Status Values

Rate Limits

Source Code Reference

​Overview

​Endpoint

​Response Format

​Example Response

​Tournament Status Values

​Rate Limits

​Related Endpoints

​Source Code Reference

Overview

Endpoint

Response Format

Example Response

Tournament Status Values

Rate Limits

Related Endpoints

Source Code Reference