Get User Profile

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

string

required

The username of the user to fetch

Query Parameters

boolean

default:"false"

Include user trophies in the response

boolean

default:"true"

Include the user’s profile information (like bio, country, links)

boolean

default:"false"

Include the user’s rating rank in each performance type

boolean

default:"false"

Include information about whether the user can be challenged (requires OAuth)

boolean

default:"false"

Include the user’s FIDE ID if available

Example Request

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

Response

string

The user’s ID (lowercase username)

string

The user’s display name

object

Performance statistics for each game variant/time control

Show Performance object

integer

Number of rated games played

integer

Current rating

integer

Rating deviation

integer

Progress in the last 12 games

boolean

Whether the rating is provisional (fewer than 10 games)

integer

Account creation timestamp in milliseconds

boolean

Whether the account is disabled (only present if true)

boolean

Whether the user violated the Terms of Service (only present if true)

object

User profile information (if profile=true and user has filled it)

Show Profile fields

string

Two-letter country code

string

User’s location

string

User’s biography

string

User’s first name

string

User’s last name

integer

FIDE rating

string

Social media and other links (space-separated)

integer

Last seen timestamp in milliseconds

object

Time spent playing

Show Play time

integer

Total play time in seconds

integer

Time spent on Lichess TV in seconds

string

Chess title (GM, IM, FM, WGM, WIM, etc.)

boolean

Whether the user is a Lichess Patron

boolean

Whether the user is verified (official accounts)

string

Full URL to the user’s profile

string

URL to the game currently being played (if any)

object

Game statistics

Show Game counts

integer

Total games played

integer

Rated games

integer

Games against AI

integer

Draw games

integer

Lost games

integer

Won games

integer

Bookmarked games

integer

Currently playing games

integer

Imported games

integer

Games played against the requester (requires authentication)

boolean

Whether the user is currently streaming

boolean

Whether the user can be followed by the requester (requires OAuth)

boolean

Whether the requester follows the user (requires OAuth)

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.

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

Get User Profile

Get real-time user data

Endpoint

Path Parameters

Query Parameters

Example Request

Response

Example Response

Rate Limiting

​Get real-time user data

​Endpoint

​Path Parameters

​Query Parameters

​Example Request

​Response

​Example Response

​Rate Limiting

Get real-time user data

Endpoint

Path Parameters

Query Parameters

Example Request

Response

Example Response

Rate Limiting