Search Games

{
  "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
}

{
  "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 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"

curl "https://lichess.org/games/search?page=1" \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "players.a=player1&players.b=player2&ratingMin=1800&ratingMax=2200"

Query Parameters

integer

default:"1"

Page number for pagination

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

Players

string

Player A username (white or black)

string

Player B username (white or black)

string

White player username

string

Black player username

string

Filter by winner. Possible values: white, black, none (draws)

Rating

integer

Minimum average rating (400-2900)

integer

Maximum average rating (400-2900)

Game Type

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

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

string

Minimum date in ISO 8601 format (e.g., 2024-01-01)

string

Maximum date in ISO 8601 format (e.g., 2024-12-31)

Time Control

integer

Minimum number of turns (half-moves)

integer

Maximum number of turns (half-moves)

integer

Minimum game duration in seconds

integer

Maximum game duration in seconds

integer

Clock initial time in seconds

integer

Clock increment in seconds

Additional Filters

string

Filter by rated status. Possible values: true, false

string

Filter games with computer analysis. Possible values: true, false

string

Filter by opening ECO code or name (e.g., C50, Italian Game)

string

Filter by game sourcePossible values:

lobby - Lobby
friend - Friend
ai - Computer
api - API
tournament - Tournament
pool - Pool
swiss - Swiss
simul - Simultaneous exhibition

object

Sort options

string

Field to sort by. Possible values: date, turns, rating

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

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

Search Games

Search games

Query Parameters

Players

Rating

Game Type

Game Status

Date Range

Time Control

Additional Filters

Response

Search limitations

Example searches

Find games between two players

Find high-rated blitz games

Find games with specific opening

Find games from a date range

Notes

​Search games

​Query Parameters

​Search Form Parameters

​Players

​Rating

​Game Type

​Game Status

​Date Range

​Time Control

​Additional Filters

​Response

​Search limitations

​Example searches

​Find games between two players

​Find high-rated blitz games

​Find games with specific opening

​Find games from a date range

​Notes

Search games

Query Parameters

Search Form Parameters

Players

Rating

Game Type

Game Status

Date Range

Time Control

Additional Filters

Response

Search limitations

Example searches

Find games between two players

Find high-rated blitz games

Find games with specific opening

Find games from a date range

Notes