Simuls

Simuls API

Access simultaneous exhibitions played on Lichess.

Namespace: LichessSharp.Api.Contracts Access: client.Simuls

---

Methods

GetCurrentAsync

Get recently created, started, and finished simuls. Returns simuls grouped by status.

Task<SimulList> GetCurrentAsync(CancellationToken cancellationToken = default)

Example:

using var client = new LichessClient();

var simuls = await client.Simuls.GetCurrentAsync();

Console.WriteLine("Currently Running:");
foreach (var simul in simuls.Started)
{
    Console.WriteLine($"  {simul.FullName}");
    Console.WriteLine($"    Host: {simul.Host.Name} ({simul.Host.Rating})");
    Console.WriteLine($"    Pairings: {simul.NbPairings}");

    foreach (var variant in simul.Variants)
    {
        Console.WriteLine($"    Variant: {variant.Name}");
    }
}

Console.WriteLine("\nRecently Created (Not Started):");
foreach (var simul in simuls.Created)
{
    Console.WriteLine($"  {simul.Name} by {simul.Host.Name}");
    Console.WriteLine($"    Applicants: {simul.NbApplicants}");

    if (simul.EstimatedStartAt.HasValue)
    {
        var startTime = DateTimeOffset.FromUnixTimeMilliseconds(simul.EstimatedStartAt.Value);
        Console.WriteLine($"    Starts at: {startTime:g}");
    }
}

Console.WriteLine("\nRecently Finished:");
foreach (var simul in simuls.Finished)
{
    Console.WriteLine($"  {simul.FullName}");

    if (simul.FinishedAt.HasValue)
    {
        var finishTime = DateTimeOffset.FromUnixTimeMilliseconds(simul.FinishedAt.Value);
        Console.WriteLine($"    Finished: {finishTime:g}");
    }
}

---

Authenticated Access

When authenticated with OAuth2, the Pending list will be populated with your created but unstarted simuls:

using var client = new LichessClient(token);

var simuls = await client.Simuls.GetCurrentAsync();

Console.WriteLine("Your Pending Simuls:");
foreach (var simul in simuls.Pending)
{
    Console.WriteLine($"  {simul.Name}");
    Console.WriteLine($"    Applicants: {simul.NbApplicants}");
}

---

Response Types

SimulList

Property	Type	Description
Pending	IReadOnlyList<Simul>	Your pending simuls (authenticated only)
Created	IReadOnlyList<Simul>	Recently created, not yet started
Started	IReadOnlyList<Simul>	Currently running
Finished	IReadOnlyList<Simul>	Recently finished

Simul

Property	Type	Description
Id	string	Simul ID
Name	string	Short name
FullName	string	Full name including host info
Host	SimulHost	Host information
Variants	IReadOnlyList<SimulVariant>	Chess variants included
IsCreated	bool	Created but not started
IsRunning	bool	Currently running
IsFinished	bool	Has finished
Text	string?	Optional description
EstimatedStartAt	long?	Estimated start (Unix ms)
StartedAt	long?	Actual start time (Unix ms)
FinishedAt	long?	Finish time (Unix ms)
NbApplicants	int	Number of applicants
NbPairings	int	Number of active games

SimulHost

Property	Type	Description
Id	string	User ID
Name	string	Username
Title	string?	Chess title (GM, IM, etc.)
Rating	int?	Rating in the simul variant
Provisional	bool?	Whether rating is provisional
GameId	string?	Current game ID if playing
Online	bool?	Whether currently online
Patron	bool?	Lichess patron status
Flair	string?	Custom flair emoji

SimulVariant

Property	Type	Description
Key	string	Variant key (e.g., "standard")
Name	string?	Display name
Icon	string?	Icon character

---

See Also

• Users API - Get user profiles
• Games API - Export and stream games