Skip to main content

​
Endpoint

GET https://lichess.org/api/puzzle/dashboard/{days}

​
Description

Get puzzle performance statistics for a specific time period. The dashboard provides aggregated metrics about puzzle solving performance, both globally and broken down by tactical themes. This endpoint powers the puzzle dashboard feature visible on the Lichess website.

​
Authentication

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

​
Path Parameters

​
days
integer
required
Number of days to include in the dashboard statistics.Supported values: 1, 2, 3, 7, 10, 14, 21, 30, 60, 90The API will round to the closest supported value if an unsupported number is provided.

​
Response

​
days
integer
required
The number of days covered by this dashboard
​
global
object
required
Overall puzzle performance across all themes
​
themes
object
required
Performance statistics broken down by puzzle themeThe object keys are theme identifiers (e.g., “fork”, “pin”, “attackingF2F7”). Each theme contains the same metrics as the global statistics.

​
Example Request

curl https://lichess.org/api/puzzle/dashboard/30 \
  -H "Authorization: Bearer {your_api_token}"

​
Example Response

{
  "days": 30,
  "global": {
    "nb": 157,
    "firstWins": 89,
    "replayWins": 23,
    "puzzleRatingAvg": 1647,
    "performance": 1714
  },
  "themes": {
    "fork": {
      "theme": "Fork",
      "results": {
        "nb": 23,
        "firstWins": 15,
        "replayWins": 3,
        "puzzleRatingAvg": 1589,
        "performance": 1741
      }
    },
    "pin": {
      "theme": "Pin",
      "results": {
        "nb": 18,
        "firstWins": 9,
        "replayWins": 4,
        "puzzleRatingAvg": 1702,
        "performance": 1702
      }
    },
    "attackingF2F7": {
      "theme": "Attacking f2 or f7",
      "results": {
        "nb": 12,
        "firstWins": 8,
        "replayWins": 2,
        "puzzleRatingAvg": 1523,
        "performance": 1690
      }
    }
  }
}

​
Dashboard Metrics Explained

​
Performance Rating

The performance rating is calculated using: 
performance = puzzleRatingAvg - 500 + round(1000 * firstWins / nb)
This gives a rough estimate of your playing strength in that theme:
  • Solving 50% of puzzles on first try = performance near puzzle rating average
  • Solving 75% on first try = performance ~250 points above average
  • Solving 90% on first try = performance ~400 points above average

​
Theme Statistics

Only themes with significant activity are included:
  • Must have attempted at least nb > global.nb / 40 puzzles
  • Very common themes like “mate” are excluded from the breakdown
  • Length-based themes (“short”, “long”) are excluded
  • Mate-in-X themes are excluded from analysis

​
Time Periods

Supported day values and their use cases:
  • 1-3 days: Recent daily performance
  • 7 days: Weekly progress tracking
  • 14-30 days: Monthly analysis (most commonly used)
  • 60-90 days: Long-term trend analysis

​
Rate Limiting

This endpoint is cached for 10 seconds per user/days combination to reduce database load.

​
Use Cases

  • Track puzzle solving improvement over time
  • Identify weak tactical themes that need practice
  • Identify strong tactical themes
  • Monitor performance trends
  • Set training goals based on theme performance
  • Build custom training plans focusing on weak areas

​
Web Interface

This API powers the puzzle dashboard available at: 
https://lichess.org/training/dashboard/{days}
For example:

Build docs developers (and LLMs) love

Get started for freeTalk to us