Skip to main content

​
Get real-time user data

This endpoint reads public data of a user. If the request is authenticated with OAuth2, the user’s private data (like email) is also returned.
If the user is not online, the response may be cached for up to 1 minute.

​
Endpoint

GET https://lichess.org/api/user/{username}

​
Path Parameters

​
username
string
required
The username of the user to fetch

​
Query Parameters

​
trophies
boolean
default:"false"
Include user trophies in the response
​
profile
boolean
default:"true"
Include the user’s profile information (like bio, country, links)
​
rank
boolean
default:"false"
Include the user’s rating rank in each performance type
​
challenge
boolean
default:"false"
Include information about whether the user can be challenged (requires OAuth)
​
fideId
boolean
default:"false"
Include the user’s FIDE ID if available

​
Example Request

curl "https://lichess.org/api/user/DrNykterstein?trophies=true"

​
Response

​
id
string
The user’s ID (lowercase username)
​
username
string
The user’s display name
​
perfs
object
Performance statistics for each game variant/time control
​
createdAt
integer
Account creation timestamp in milliseconds
​
disabled
boolean
Whether the account is disabled (only present if true)
​
tosViolation
boolean
Whether the user violated the Terms of Service (only present if true)
​
profile
object
User profile information (if profile=true and user has filled it)
​
seenAt
integer
Last seen timestamp in milliseconds
​
playTime
object
Time spent playing
​
title
string
Chess title (GM, IM, FM, WGM, WIM, etc.)
​
patron
boolean
Whether the user is a Lichess Patron
​
verified
boolean
Whether the user is verified (official accounts)
​
url
string
Full URL to the user’s profile
​
playing
string
URL to the game currently being played (if any)
​
count
object
Game statistics
​
streaming
boolean
Whether the user is currently streaming
​
followable
boolean
Whether the user can be followed by the requester (requires OAuth)
​
following
boolean
Whether the requester follows the user (requires OAuth)
​
blocking
boolean
Whether the requester blocks the user (requires OAuth)

​
Example Response

{
  "id": "drnykterstein",
  "username": "DrNykterstein",
  "perfs": {
    "blitz": {
      "games": 6205,
      "rating": 3003,
      "rd": 45,
      "prog": 15
    },
    "rapid": {
      "games": 452,
      "rating": 2927,
      "rd": 47,
      "prog": -12
    },
    "classical": {
      "games": 34,
      "rating": 2500,
      "rd": 98,
      "prog": 0,
      "prov": true
    }
  },
  "createdAt": 1290415680000,
  "profile": {
    "country": "NO",
    "location": "Tønsberg, Norway",
    "bio": "World Chess Champion",
    "firstName": "Magnus",
    "lastName": "Carlsen",
    "fideRating": 2830,
    "links": "https://twitter.com/MagnusCarlsen"
  },
  "seenAt": 1708963200000,
  "playTime": {
    "total": 5436200,
    "tv": 12600
  },
  "title": "GM",
  "patron": true,
  "verified": true,
  "url": "https://lichess.org/@/DrNykterstein",
  "count": {
    "all": 7891,
    "rated": 6691,
    "ai": 0,
    "draw": 412,
    "loss": 2156,
    "win": 5323,
    "bookmark": 71,
    "playing": 1,
    "import": 0
  },
  "streaming": false
}

​
Rate Limiting

This endpoint is rate-limited based on:
  • Whether the user is online (offline users have cached responses)
  • Whether the request is authenticated
  • The user’s verification status
Authenticated and verified users have higher rate limits.

Build docs developers (and LLMs) love

Get started for freeTalk to us