Skip to main content

​
Endpoint

GET https://lichess.org/api/puzzle/activity

​
Description

Download your puzzle activity in ndjson format. Each line represents a puzzle round, including the puzzle details and whether it was solved correctly. Puzzle activity is streamed as ndjson (newline-delimited JSON).

​
Authentication

This endpoint requires authentication with OAuth2 or API token.
Required OAuth2 scopes:
  • puzzle:read
  • web:mod (for mobile clients)

​
Query Parameters

​
max
integer
default:"unlimited"
Maximum number of puzzle rounds to return. Must be at least 1.If not specified, all puzzle activity will be streamed.
​
before
integer
Return only puzzle activity before this timestamp (in milliseconds since epoch).Can be used for pagination by passing the timestamp of the oldest entry from a previous request.
​
since
integer
Return only puzzle activity since this timestamp (in milliseconds since epoch).Useful for fetching only recent activity.

​
Response Format

The response is streamed as ndjson (newline-delimited JSON). Each line is a JSON object representing one puzzle round.
​
date
integer
required
Unix timestamp in milliseconds when the puzzle was attempted
​
win
boolean
required
Whether the puzzle was solved correctly on the first attempt
​
puzzle
object
required
The puzzle information

​
Example Request

curl https://lichess.org/api/puzzle/activity?max=10 \
  -H "Authorization: Bearer {your_api_token}"

​
Example Response

{"date":1709740800000,"win":true,"puzzle":{"id":"abc12","fen":"r1bqkb1r/pppp1ppp/2n2n2/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 4 4","rating":1456,"plays":8234,"solution":["f3e5","f6e4","d1h5"],"themes":["fork","short","opening"],"lastMove":"g8f6"}}
{"date":1709737200000,"win":false,"puzzle":{"id":"def34","fen":"rnbqkbnr/ppp2ppp/4p3/3p4/2PP4/8/PP2PPPP/RNBQKBNR w KQkq - 0 3","rating":1523,"plays":5432,"solution":["c4d5","e6d5","g1f3"],"themes":["opening","advantage"],"lastMove":"d7d5"}}

​
Rate Limiting

This endpoint is subject to standard Lichess API rate limits:
  • Authenticated requests: More generous limits
  • The stream is throttled to ~20 puzzle rounds per second
  • Total concurrent connections are limited per IP and user

​
NDJSON Format

The response uses newline-delimited JSON (ndjson) format:
  • Each line is a complete JSON object
  • Lines are separated by newline characters (\n)
  • Process line-by-line for memory efficiency
  • Stream can be consumed in real-time

​
Use Cases

  • Analyze your puzzle solving performance over time
  • Export puzzle activity for external analysis
  • Track improvement in specific puzzle themes
  • Build custom puzzle statistics dashboards
  • Sync puzzle data with third-party training tools

Build docs developers (and LLMs) love

Get started for freeTalk to us