Session Browser

Session Browser

The session browser lists the open, public game sessions in the caller's Game Project. A player can select a lobby from the list and join it. The session browser adds to the matchmaker and join codes. It does not replace them.

For dedicated servers that stay up between matches, use the Server Browser.

Which discovery path

Path	Use it when
Session browser (GET /v1/game-sessions)	The player wants to see the lobbies and select one by map, mode, player count, or host name.
Matchmaker (POST /v1/matchmaker/tickets)	The game selects for the player, by skill or mode. The UI shows no lobby list.
Join code (GET /v1/game-session?joinCode=…)	The player got a code by voice chat or an invite, and wants to join that session. This includes a private session.

The browser never lists a private session ("private": true at creation). Only the host, members, and invited players can find a private session, by join code or invite. Matchmaking creates private sessions, so they never show in the browser.

List sessions

curl -s http://localhost:8080/v1/game-sessions \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>"

{
  "items": [
    {
      "session_id": "gs_9f86d081884c7d659a2feaa0c55ad015",
      "title_id": "my-game",
      "props": {"map": "arena-2"},
      "player_count": 3,
      "max_players": 8,
      "host_player_id": 87,
      "host_display_name": "Nova Fox",
      "created_at": "2026-01-02T15:04:05Z"
    }
  ],
  "next_cursor": ""
}

To join a listed session, call POST /v1/game-session/{id}/join with the session_id. See Game Sessions and Invites. The list shows public fields only. It does not show join codes or peer addresses. A player sees the peers after the join succeeds.

Filters and pagination

Parameter	Effect
title_id	Return only sessions with this title_id. Use it to keep game modes or playlists in one Game Project apart.
limit	Page size. Default 50, maximum 100.
cursor	The next_cursor value from the previous page. An empty next_cursor means the last page.

What is listed

The browser lists a session only when all of these are true:

• It is public ("private": false, the default).
• Its state is open.
• It has not expired. Member heartbeats extend expires_at.
• It has space: player_count is less than max_players.
• At least one member sent a heartbeat in the last 30 seconds.

player_count counts the members with a heartbeat in the last 30 seconds. The join check uses the same count. If all members stop their heartbeats, nobody can play in the lobby. So the lobby leaves the list before it expires. Keep the host sending heartbeats (POST /v1/game-session/{id}/heartbeat) while the lobby waits for players.

Two players can try to join the last free slot at the same time. The join route decides. The second player gets 409 session is full and must get the list again.

Full reference: the /v1/game-sessions operation.