curl --request GET \
--url https://api.simpl.gg/v1/lobbies/{lobby_id} \
--header 'api-key: <api-key>'import requests
url = "https://api.simpl.gg/v1/lobbies/{lobby_id}"
headers = {"api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'api-key': '<api-key>'}};
fetch('https://api.simpl.gg/v1/lobbies/{lobby_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.simpl.gg/v1/lobbies/{lobby_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.simpl.gg/v1/lobbies/{lobby_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.simpl.gg/v1/lobbies/{lobby_id}")
.header("api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.simpl.gg/v1/lobbies/{lobby_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"lobby_id": "lobby_456",
"queue_id": "ranked_2v2",
"name": "Austin's lobby",
"status": "in_game",
"region": "iad",
"host_player_id": "player_1",
"is_private": false,
"invite_code": "SIMPL-K7Q2F1",
"max_players": 4,
"current_players": 2,
"settings": {
"map": "forest",
"mode": "ctf"
},
"players": [
{
"player_id": "player_1",
"is_host": true,
"state": {
"mmr": 1500,
"team": "team_1"
},
"joined_at": "2026-09-21T14:00:00Z"
},
{
"player_id": "player_2",
"is_host": false,
"state": {
"mmr": 1480,
"team": "team_1"
},
"joined_at": "2026-09-21T14:00:05Z"
}
],
"server": {
"instance_id": "abc123",
"match_id": "xyz789",
"region": "iad",
"status": "running",
"network_ports": [
{
"name": "game_udp",
"protocol": "udp",
"internal_port": 7777,
"external_port": 30412,
"host": "37.16.24.10",
"tls_enabled": false
}
]
},
"match_id": "xyz789",
"created_at": "2026-09-21T14:00:00Z",
"updated_at": "2026-09-21T14:02:11Z"
}Get a lobby
Returns the full lobby, including players and, once the match is
running, server with connection details. This is the polling fallback
for clients that cannot hold an SSE connection.
curl --request GET \
--url https://api.simpl.gg/v1/lobbies/{lobby_id} \
--header 'api-key: <api-key>'import requests
url = "https://api.simpl.gg/v1/lobbies/{lobby_id}"
headers = {"api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'api-key': '<api-key>'}};
fetch('https://api.simpl.gg/v1/lobbies/{lobby_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.simpl.gg/v1/lobbies/{lobby_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.simpl.gg/v1/lobbies/{lobby_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.simpl.gg/v1/lobbies/{lobby_id}")
.header("api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.simpl.gg/v1/lobbies/{lobby_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"lobby_id": "lobby_456",
"queue_id": "ranked_2v2",
"name": "Austin's lobby",
"status": "in_game",
"region": "iad",
"host_player_id": "player_1",
"is_private": false,
"invite_code": "SIMPL-K7Q2F1",
"max_players": 4,
"current_players": 2,
"settings": {
"map": "forest",
"mode": "ctf"
},
"players": [
{
"player_id": "player_1",
"is_host": true,
"state": {
"mmr": 1500,
"team": "team_1"
},
"joined_at": "2026-09-21T14:00:00Z"
},
{
"player_id": "player_2",
"is_host": false,
"state": {
"mmr": 1480,
"team": "team_1"
},
"joined_at": "2026-09-21T14:00:05Z"
}
],
"server": {
"instance_id": "abc123",
"match_id": "xyz789",
"region": "iad",
"status": "running",
"network_ports": [
{
"name": "game_udp",
"protocol": "udp",
"internal_port": 7777,
"external_port": 30412,
"host": "37.16.24.10",
"tls_enabled": false
}
]
},
"match_id": "xyz789",
"created_at": "2026-09-21T14:00:00Z",
"updated_at": "2026-09-21T14:02:11Z"
}Authorizations
Per-project client key, prefixed ck_live_. Player-facing endpoints
only, and browse never returns private lobbies. Safe to ship in a game
binary: a leak exposes one project's player surface, nothing else.
Headers
Optional player identity. When present the response may include player-specific fields. Trusted verbatim, never verified.
1 - 128"player_1"
Path Parameters
Lobby identifier.
"lobby_456"
Response
The lobby.
"lobby_456"
"ranked_2v2"
Lobby lifecycle:
waiting → in_queue → matched → in_game → waiting (rematch-ready)
↓
→ waiting (timeout/cancel/no opponents)
waiting → starting → in_game (host started directly)
→ waiting (server create failed)
waiting, in_queue, matched, starting, in_game "player_1"
Private lobbies never appear in GET /v1/lobbies for client keys, and
are joinable by invite code only.
1 <= x <= 1004
x >= 02
Show child attributes
Show child attributes
"Austin's lobby"
Datacenter region a server runs in. 16 regions are supported.
| code | location |
|---|---|
ams | Amsterdam, Netherlands |
arn | Stockholm, Sweden |
bom | Mumbai, India |
cdg | Paris, France |
dfw | Dallas, Texas (US) |
ewr | Secaucus, NJ (US) |
fra | Frankfurt, Germany |
iad | Ashburn, Virginia (US) |
lax | Los Angeles, California (US) |
lhr | London, United Kingdom |
nrt | Tokyo, Japan |
ord | Chicago, Illinois (US) |
sin | Singapore, Singapore |
sjc | San Jose, California (US) |
syd | Sydney, Australia |
yyz | Toronto, Canada |
Every region is available to every project. Capacity is Simpl's problem, not yours: pick the region closest to your players.
ams, arn, bom, cdg, dfw, ewr, fra, iad, lax, lhr, nrt, ord, sin, sjc, syd, yyz "iad"
Generated per the queue's invite_code_config. Null when the queue has
invite codes disabled.
"SIMPL-K7Q2F1"
Free-form, game-specific lobby settings: map, mode, difficulty, whatever
the game needs. Host-writable via
PATCH /v1/lobbies/{lobby_id}/settings.
{
"map": "forest",
"mode": "ctf",
"difficulty": "hard"
}
Connection details for the game server backing this lobby. Present once the
server is running. Connection-relevant fields only. Call
GET /v1/servers/{instance_id} with a server key for the full object.
Show child attributes
Show child attributes
"xyz789"