Skip to main content

​
Export a single game

Download one game in PGN or JSON format. 
curl "https://lichess.org/game/export/q7ZvsdUF"

​
Path Parameters

​
gameId
string
required
The game ID (8 characters)

​
Query Parameters

​
moves
boolean
default:"true"
Include the PGN moves
​
tags
boolean
default:"true"
Include the PGN tags
​
clocks
boolean
default:"true"
Include clock comments in the PGN moves when available
​
evals
boolean
default:"true"
Include analysis evaluation comments in the PGN when available
​
opening
boolean
default:"true"
Include the opening name
​
literate
boolean
default:"false"
Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination
​
pgnInJson
boolean
default:"false"
Include the full PGN within the JSON response, in a pgn field
​
accuracy
boolean
default:"false"
Include accuracy percent of each player, when available
​
division
boolean
default:"true"
Include the division information (opening, middle game, end game boundaries)

​
Response Format

By default, games are exported in PGN format. Set the Accept header to application/x-ndjson or application/json to get JSON. 
[Event "Rated Blitz game"]
[Site "https://lichess.org/q7ZvsdUF"]
[Date "2024.03.06"]
[White "player1"]
[Black "player2"]
[Result "1-0"]
[UTCDate "2024.03.06"]
[UTCTime "14:30:00"]
[WhiteElo "2000"]
[BlackElo "1980"]
[WhiteRatingDiff "+10"]
[BlackRatingDiff "-10"]
[Variant "Standard"]
[TimeControl "180+0"]
[ECO "C50"]
[Opening "Italian Game"]
[Termination "Normal"]

1. e4 e5 2. Nf3 Nc6 3. Bc4 1-0

​
Export games by IDs

Download multiple games by their IDs. 
curl -X POST "https://lichess.org/api/games/export/_ids" \
  -H "Content-Type: text/plain" \
  -d "q7ZvsdUF,iAnNeY0A,oX66A8F9"

​
Request Body

​
ids
string
required
Game IDs separated by commas. Max 300 IDs (or 600 for OAuth).

​
Query Parameters

Same as single game export, plus:
​
players
string
URL of a text file containing real names and ratings for PGN tags, one player per line separated by semicolons.

​
Response

Returns an ND-JSON stream where each line is a JSON object representing one game, or a stream of PGN games separated by double newlines.

​
Export games by user

Download all games of a user. 
curl "https://lichess.org/api/games/user/player1"

​
Path Parameters

​
username
string
required
The username

​
Query Parameters

​
since
integer
Download games played since this timestamp in milliseconds
​
until
integer
Download games played until this timestamp in milliseconds
​
max
integer
Maximum number of games to download. Leave empty to download all games.
​
vs
string
Filter games by opponent username
​
rated
boolean
Filter rated or casual games
​
perfType
string
Filter by game type (perf). Multiple types can be specified, separated by commas.Possible values: ultraBullet, bullet, blitz, rapid, classical, correspondence, chess960, crazyhouse, antichess, atomic, horde, kingOfTheHill, racingKings, threeCheck
​
color
string
Filter by color played. Possible values: white, black
​
analysed
boolean
Filter games with or without a computer analysis available
​
ongoing
boolean
default:"false"
Include ongoing games. The last 3 moves will be omitted.
​
finished
boolean
default:"true"
Include finished games. Set to false to only get ongoing games.
​
sort
string
default:"dateDesc"
Sort order. Possible values: dateAsc, dateDesc
Plus all the formatting parameters from single game export.

​
Response

Returns an ND-JSON stream where each line is a JSON object representing one game, or a stream of PGN games separated by double newlines. 
{"id":"q7ZvsdUF","rated":true,"variant":"standard","speed":"blitz","perf":"blitz","createdAt":1709736600000,"lastMoveAt":1709736780000,"status":"mate","players":{"white":{"user":{"name":"player1","id":"player1"},"rating":2000,"ratingDiff":10},"black":{"user":{"name":"player2","id":"player2"},"rating":1980,"ratingDiff":-10}},"winner":"white","moves":"e4 e5 Nf3 Nc6 Bc4"}
{"id":"iAnNeY0A","rated":true,"variant":"standard","speed":"rapid","perf":"rapid","createdAt":1709650200000,"lastMoveAt":1709651000000,"status":"resign","players":{"white":{"user":{"name":"player1","id":"player1"},"rating":1850,"ratingDiff":8},"black":{"user":{"name":"opponent","id":"opponent"},"rating":1870,"ratingDiff":-8}},"winner":"white","moves":"d4 d5 c4 e6"}

​
Export imported games

Download all PGN games previously imported by a user. 
curl "https://lichess.org/api/games/export/imports" \
  -H "Authorization: Bearer <your_token>"

​
Authentication

Requires OAuth token with game:read scope.

​
Response

Returns a stream of PGN games separated by triple newlines.

​
Export bookmarked games

Download all games bookmarked by the authenticated user. 
curl "https://lichess.org/api/games/export/bookmarks" \
  -H "Authorization: Bearer <your_token>"

​
Authentication

Requires OAuth token with game:read scope.

​
Query Parameters

​
since
integer
Download games bookmarked since this timestamp in milliseconds
​
until
integer
Download games bookmarked until this timestamp in milliseconds
​
max
integer
Maximum number of games to download (default 5000)
​
sort
string
default:"dateDesc"
Sort order. Possible values: dateAsc, dateDesc
Plus all the formatting parameters from single game export.

​
Response

Returns an ND-JSON stream or PGN stream of bookmarked games.

Build docs developers (and LLMs) love

Get started for freeTalk to us