v3

latestOpenAPI 3.1.0AGPL-3.0-or-later2026-07-311871891.1 MB

Users

Get real-time users status

Read the online, playing and streaming flags of several users. This API is very fast and cheap on lichess side. So you can call it quite often (like once every 5 seconds). Use it to track players and know when they're connected on lichess and playing games.

get/api/users/status

Query parameters

idsstring required

User IDs separated by commas. Up to 100 IDs.

withSignalboolean

Also return the network signal of the player, when available. It ranges from 1 (poor connection, lag > 500ms) to 4 (great connection, lag < 150ms) Defaults to false to preserve server resources.

withGameIdsboolean

Also return the ID of the game being played, if any, for each player, in a playingId field. Defaults to false to preserve server resources.

withGameMetasboolean

Also return the id, time control and variant of the game being played, if any, for each player, in a playing field. Defaults to false to preserve server resources. Disables withGameIds.

Response

The list of users and their respective statuses.

idstring required

namestring required

flairstring

See available flair list and images

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

onlineboolean

playingboolean

streamingboolean

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.

All 187 operations