Skip to main content

​
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:
​
created
array
Array of scheduled tournaments that haven’t started yet
​
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.

​
Source Code Reference

Implementation can be found in:
  • app/controllers/Api.scala:146 - currentTournaments method
  • app/controllers/Tournament.scala:146 - Tournament API handling

Build docs developers (and LLMs) love

Get started for freeTalk to us