Sign in

v3

OpenAPI 3.1.0AGPL-3.0-or-later2026-07-311871891.1 MB
Users

Get users by ID

Get up to 300 users by their IDs. Users are returned in the same order as the IDs. The method is POST to allow a longer list of IDs to be sent in the request body. Please do not try to download all the Lichess users with this endpoint, or any other endpoint. An API is not a way to fully export a website. We do not provide a full download of the Lichess users. This endpoint is limited to 8,000 users every 10 minutes, and 120,000 every day.

post/api/users

Query parameters

profileboolean

Include user profile data

rankboolean

Include global lichess ranking for each perf

Response

The list of users.

idstring required
usernamestring required
title'GM' | 'WGM' | 'IM' | 'WIM' | 'FM' | 'WFM' | 'NM' | 'CM' | 'WCM' | 'WNM' | 'LM' | 'BOT'

only appears if the user is a titled player or a bot user

flairstring

See available flair list and images

createdAtinteger
disabledboolean

only appears if a user's account is closed

tosViolationboolean

only appears if a user's account is marked for the violation of Lichess TOS

seenAtinteger
patronboolean

Use patronColor value instead to determine if player is a patron.

patronColorinteger

Players can choose a color for their Patron wings. See here for the color mappings.

The presence of this field indicates the player is an active Patron.

verifiedboolean

Example response

[
  {
    "profile": {
      "flag": "EC",
      "bio": "Free bugs!",
      "realName": "Thibault Duplessis",
      "fideRating": 1500,
      "uscfRating": 1500,
      "ecfRating": 1500,
      "cfcRating": 1500,
      "rcfRating": 1500,
      "dsbRating": 1500,
      "links": "github.com/ornicar\r\nmas.to/@thibault"
    }
  }
]