Skip to main content

​
Get Round Details

Get detailed information about a specific broadcast round. 
curl -X GET 'https://lichess.org/api/broadcast/{slug1}/{slug2}/{roundId}' \
  -H 'Accept: application/json'

​
Endpoint

GET https://lichess.org/api/broadcast/{slug1}/{slug2}/{roundId}

​
Path Parameters

​
slug1
string
required
Tournament slug (used for URL formatting)
​
slug2
string
required
Round slug (used for URL formatting)
​
roundId
string
required
The round ID (8 characters)

​
Response

​
round
object
Round information
​
tour
object
Parent tournament information
​
study
object
Study settings and permissions
​
games
array
Array of chapter previews (games) in the round
​
group
object
Group information if applicable
​
photos
object
Player photos keyed by player name
​
isSubscribed
boolean
Whether the current user is subscribed (requires authentication)
​
socketVersion
integer
WebSocket version for real-time updates

​
Authentication

Optional. Provide an OAuth token with study:read scope to:
  • Access private broadcasts
  • Get subscription status
  • Receive socket version for real-time updates

​
Get My Rounds

Get broadcast rounds that you have access to manage. 
curl -X GET 'https://lichess.org/api/broadcast/my-rounds?nb=20' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/x-ndjson'

​
Endpoint

GET https://lichess.org/api/broadcast/my-rounds

​
Query Parameters

​
nb
integer
Maximum number of rounds to return

​
Response

Returns a stream of rounds in NDJSON format where you have contributor access.

​
Authentication

Required. OAuth token with study:read scope.

​
Export Round PGN

Download all games from a broadcast round as PGN. 
curl -X GET 'https://lichess.org/api/broadcast/round/{roundId}.pgn' \
  --output round.pgn

​
Endpoint

GET https://lichess.org/api/broadcast/round/{roundId}.pgn

​
Path Parameters

​
roundId
string
required
The round ID (8 characters)

​
Response

Returns PGN data for all games in the round as application/x-chess-pgn.

​
Stream Round Games

Stream all games from a broadcast round in real-time as they are updated. 
curl -X GET 'https://lichess.org/api/stream/broadcast/round/{roundId}.pgn' \
  -H 'Accept: application/x-chess-pgn'

​
Endpoint

GET https://lichess.org/api/stream/broadcast/round/{roundId}.pgn

​
Path Parameters

​
roundId
string
required
The round ID (8 characters)

​
Response

Returns a persistent streaming connection that sends updated PGN data as games progress. The stream stays open and sends updates as they occur.
The stream includes keep-alive spaces every 60 seconds to maintain the connection.

​
Rate Limits

  • Higher limits for verified users
  • Connection limits apply per IP address

​
Reset Round

Reset a broadcast round, clearing all games and allowing it to be re-synced. 
curl -X POST 'https://lichess.org/api/broadcast/round/{roundId}/reset' \
  -H 'Authorization: Bearer {token}'

​
Endpoint

POST https://lichess.org/api/broadcast/round/{roundId}/reset

​
Path Parameters

​
roundId
string
required
The round ID (8 characters)

​
Response

Returns success confirmation.

​
Authentication

Required. OAuth token with study:write scope. You must be a contributor to the broadcast.
This action cannot be undone. All games in the round will be removed.

​
Get Round Stats

Get viewership statistics for a broadcast round. 
curl -X GET 'https://lichess.org/broadcast/round/{roundId}/stats' \
  -H 'Accept: application/json'

​
Endpoint

GET https://lichess.org/broadcast/round/{roundId}/stats

​
Path Parameters

​
roundId
string
required
The round ID (8 characters)

​
Response

​
viewers
array
Array of viewer count data points. Each element is [timestamp, count] where timestamp is in seconds and count is the number of concurrent viewers.
​
unique
integer
Total number of unique viewers (if greater than 0)

Build docs developers (and LLMs) love

Get started for freeTalk to us