Export Games

Export a single game

Download one game in PGN or JSON format.

curl "https://lichess.org/game/export/q7ZvsdUF"

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

Path Parameters

string

required

The game ID (8 characters)

Query Parameters

boolean

default:"true"

Include the PGN moves

boolean

default:"true"

Include the PGN tags

boolean

default:"true"

Include clock comments in the PGN moves when available

boolean

default:"true"

Include analysis evaluation comments in the PGN when available

boolean

default:"true"

Include the opening name

boolean

default:"false"

Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination

boolean

default:"false"

Include the full PGN within the JSON response, in a pgn field

boolean

default:"false"

Include accuracy percent of each player, when available

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

{
  "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",
  "opening": {
    "eco": "C50",
    "name": "Italian Game",
    "ply": 5
  },
  "moves": "e4 e5 Nf3 Nc6 Bc4",
  "clock": {
    "initial": 180,
    "increment": 0,
    "totalTime": 180
  }
}

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

string

required

Game IDs separated by commas. Max 300 IDs (or 600 for OAuth).

Query Parameters

Same as single game export, plus:

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"

curl "https://lichess.org/api/games/user/player1?max=20&rated=true&perfType=blitz,rapid"

Path Parameters

string

required

The username

Query Parameters

integer

Download games played since this timestamp in milliseconds

integer

Download games played until this timestamp in milliseconds

integer

Maximum number of games to download. Leave empty to download all games.

string

Filter games by opponent username

boolean

Filter rated or casual games

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

string

Filter by color played. Possible values: white, black

boolean

Filter games with or without a computer analysis available

boolean

default:"false"

Include ongoing games. The last 3 moves will be omitted.

boolean

default:"true"

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

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

integer

Download games bookmarked since this timestamp in milliseconds

integer

Download games bookmarked until this timestamp in milliseconds

integer

Maximum number of games to download (default 5000)

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.

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

Export a single game

Path Parameters

Query Parameters

Response Format

Export games by IDs

Request Body

Query Parameters

Response

Export games by user

Path Parameters

Query Parameters

Response

Export imported games

Authentication

Response

Export bookmarked games

Authentication

Query Parameters

Response

​Export a single game

​Path Parameters

​Query Parameters

​Response Format

​Export games by IDs

​Request Body

​Query Parameters

​Response

​Export games by user

​Path Parameters

​Query Parameters

​Response

​Export imported games

​Authentication

​Response

​Export bookmarked games

​Authentication

​Query Parameters

​Response

Export a single game

Path Parameters

Query Parameters

Response Format

Export games by IDs

Request Body

Query Parameters

Response

Export games by user

Path Parameters

Query Parameters

Response

Export imported games

Authentication

Response

Export bookmarked games

Authentication

Query Parameters

Response