Sign in

v3

OpenAPI 3.1.0AGPL-3.0-or-later2026-07-311871891.1 MB
Games

Export games of a user

Download all games of any user in PGN or ndjson format. Games are sorted by reverse chronological order (most recent first). We recommend streaming the response, for it can be very long. https://lichess.org/@/german11 for instance has more than 500,000 games. The game stream is throttled, depending on who is making the request:

  • Anonymous request: 20 games per second
  • OAuth2 authenticated request: 30 games per second
  • Authenticated, downloading your own games: 60 games per second
get/api/games/user/{username}

Path parameters

usernamestring required

The user name.

Query parameters

sinceinteger

Download games played since this timestamp. Defaults to account creation date.

untilinteger

Download games played until this timestamp. Defaults to now.

maxinteger

How many games to download. Leave empty to download all games.

vsstring

[Filter] Only games played against this opponent

ratedboolean

[Filter] Only rated (true) or casual (false) games

perfType'ultraBullet' | 'bullet' | 'blitz' | 'rapid' | 'classical' | 'correspondence' | 'chess960' | 'crazyhouse' | 'antichess' | 'atomic' | 'horde' | 'kingOfTheHill' | 'racingKings' | 'threeCheck'

[Filter] Only games in these speeds or variants. Multiple perf types can be specified, separated by a comma. Example: blitz,rapid,classical

color'white' | 'black'

[Filter] Only games played as this color.

analysedboolean

[Filter] Only games with or without a computer analysis available

movesboolean

Include the PGN moves.

pgnInJsonboolean

Include the full PGN within the JSON response, in a pgn field. The response type must be set to application/x-ndjson by the request Accept header.

tagsboolean

Include the PGN tags.

clocksboolean

Include clock status when available. Either as PGN comments: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] } Or in a clocks JSON field, as centisecond integers, depending on the response type.

evalsboolean

Include analysis evaluations and comments, when available. Either as PGN comments: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] } Or in an analysis JSON field, depending on the response type.

accuracyboolean

Include accuracy percent of each player, when available. Only available in JSON.

openingboolean

Include the opening name. Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

divisionboolean

Plies which mark the beginning of the middlegame and endgame. Only available in JSON

ongoingboolean

Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API.

finishedboolean

Include finished games. Set to false to only get ongoing games.

literateboolean

Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. Example: 5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)

lastFenboolean

Include the X-FEN notation of the last position of the game. The response type must be set to application/x-ndjson by the request Accept header.

withBookmarkedboolean

Add a bookmarked: true JSON field when the logged in user has bookmarked the game. The response type must be set to application/x-ndjson by the request Accept header.

sort'dateAsc' | 'dateDesc'

Sort order of the games.

Headers

Accept'application/x-chess-pgn' | 'application/x-ndjson'

Specify the desired response format. Use application/x-chess-pgn to get the games in PGN format. Use application/x-ndjson to get the games in ndjson format. Read about ndjson here and how you can parse it in Javascript.

Response

The games of the user.