Skip to main content

​
Search games

Search games using various filters. This endpoint provides a web interface and API access to search through all Lichess games.
Game search requires authentication. Anonymous users cannot search games.
curl "https://lichess.org/games/search?page=1"

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination

​
Search Form Parameters

These parameters are typically submitted via POST in the request body:

​
Players

​
players.a
string
Player A username (white or black)
​
players.b
string
Player B username (white or black)
​
players.white
string
White player username
​
players.black
string
Black player username
​
players.winner
string
Filter by winner. Possible values: white, black, none (draws)

​
Rating

​
ratingMin
integer
Minimum average rating (400-2900)
​
ratingMax
integer
Maximum average rating (400-2900)

​
Game Type

​
perf
array
Game type(s). Multiple values can be selected.Possible values:
  • ultraBullet - UltraBullet
  • bullet - Bullet
  • blitz - Blitz
  • rapid - Rapid
  • classical - Classical
  • correspondence - Correspondence
  • chess960 - Chess960
  • crazyhouse - Crazyhouse
  • antichess - Antichess
  • atomic - Atomic
  • horde - Horde
  • kingOfTheHill - King of the Hill
  • racingKings - Racing Kings
  • threeCheck - Three-check

​
Game Status

​
status
string
Filter by game result/statusPossible values:
  • mate - Checkmate
  • resign - Resignation
  • stalemate - Stalemate
  • timeout - Time out
  • draw - Draw
  • outoftime - Out of time
  • cheat - Cheat detected

​
Date Range

​
date.min
string
Minimum date in ISO 8601 format (e.g., 2024-01-01)
​
date.max
string
Maximum date in ISO 8601 format (e.g., 2024-12-31)

​
Time Control

​
turnsMin
integer
Minimum number of turns (half-moves)
​
turnsMax
integer
Maximum number of turns (half-moves)
​
durationMin
integer
Minimum game duration in seconds
​
durationMax
integer
Maximum game duration in seconds
​
clockInit
integer
Clock initial time in seconds
​
clockInc
integer
Clock increment in seconds

​
Additional Filters

​
rated
string
Filter by rated status. Possible values: true, false
​
analysed
string
Filter games with computer analysis. Possible values: true, false
​
opening
string
Filter by opening ECO code or name (e.g., C50, Italian Game)
​
source
string
Filter by game sourcePossible values:
  • lobby - Lobby
  • friend - Friend
  • ai - Computer
  • api - API
  • tournament - Tournament
  • pool - Pool
  • swiss - Swiss
  • simul - Simultaneous exhibition
​
sort
object
Sort options
​
sort.field
string
Field to sort by. Possible values: date, turns, rating
​
sort.order
string
Sort order. Possible values: asc, desc

​
Response

For web requests, returns an HTML page with search results. For API requests (with appropriate Accept headers), returns a JSON paginator object: 
{
  "currentPage": 1,
  "maxPerPage": 15,
  "currentPageResults": [
    {
      "id": "q7ZvsdUF",
      "rated": true,
      "variant": "standard",
      "speed": "blitz",
      "perf": "blitz",
      "createdAt": 1709736600000,
      "lastMoveAt": 1709736780000,
      "status": "mate",
      "source": "lobby",
      "players": {
        "white": {
          "user": {
            "name": "player1",
            "id": "player1"
          },
          "rating": 2000,
          "ratingDiff": 10
        },
        "black": {
          "user": {
            "name": "player2",
            "id": "player2"
          },
          "rating": 1980,
          "ratingDiff": -10
        }
      },
      "winner": "white",
      "opening": {
        "eco": "C50",
        "name": "Italian Game",
        "ply": 5
      },
      "moves": "e4 e5 Nf3 Nc6 Bc4",
      "url": "https://lichess.org/q7ZvsdUF"
    }
  ],
  "nbResults": 142,
  "previousPage": null,
  "nextPage": 2,
  "nbPages": 10
}

​
Search limitations

Game search is rate-limited to prevent abuse:
  • Anonymous users cannot search
  • Authenticated users have a concurrency limit (one search at a time per IP)
  • Search cost increases with page number
  • Maximum 100 pages per search

​
Example searches

​
Find games between two players

curl "https://lichess.org/games/search?page=1" \
  -X POST \
  -H "Cookie: lila2=your_session_cookie" \
  -d "players.a=Magnus&players.b=Hikaru"

​
Find high-rated blitz games

curl "https://lichess.org/games/search?page=1" \
  -X POST \
  -H "Cookie: lila2=your_session_cookie" \
  -d "ratingMin=2500&perf=blitz&analysed=true"

​
Find games with specific opening

curl "https://lichess.org/games/search?page=1" \
  -X POST \
  -H "Cookie: lila2=your_session_cookie" \
  -d "opening=Sicilian Defense&ratingMin=2000"

​
Find games from a date range

curl "https://lichess.org/games/search?page=1" \
  -X POST \
  -H "Cookie: lila2=your_session_cookie" \
  -d "date.min=2024-01-01&date.max=2024-01-31&perf=classical"

​
Notes

  • Game search uses Elasticsearch for indexing and searching
  • Results are sorted by relevance by default
  • The search index may have a slight delay (typically under 1 minute) for newly finished games
  • Some filters require games to be analyzed (e.g., accuracy, complex position queries)
  • Tournament and Swiss games can be filtered by tournament/swiss ID in the game metadata

Build docs developers (and LLMs) love

Get started for freeTalk to us