Request Multiplayer Server

Request a multiplayer server session. Accepts tokens for title and if game client access is enabled, allows game client to request a server with player entity token.

Allowed entity token types: title, title_player_account

Error codes

This operation may return the following PlayFab errors:

Error	Code
APINotEnabledForGameClientAccess	1082
MultiplayerServerBadRequest	1382
MultiplayerServerForbidden	1384
MultiplayerServerInternalServerError	1387
MultiplayerServerNotFound	1385
MultiplayerServerTooManyRequests	1380
MultiplayerServerUnauthorized	1383
MultiplayerServerUnavailable	1388
ProductDisabledForTitle	1609

POST

MultiplayerServer

RequestMultiplayerServer

Request Multiplayer Server

curl --request POST \
  --url https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer \
  --header 'Content-Type: application/json' \
  --header 'X-EntityToken: <api-key>' \
  --data '
{
  "BuildId": "21781fa8-096d-4d9c-b699-75433d579285",
  "SessionId": "02bdef0e-e01e-4b29-8efe-ff9f47a06d8c",
  "SessionCookie": "U2Vzc2lvbkNvb2tpZQ==",
  "InitialPlayers": [
    "gamer1",
    "gamer2"
  ],
  "PreferredRegions": [
    "SouthCentralUs",
    "WestUs"
  ]
}
'

import requests

url = "https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer"

payload = {
    "BuildId": "21781fa8-096d-4d9c-b699-75433d579285",
    "SessionId": "02bdef0e-e01e-4b29-8efe-ff9f47a06d8c",
    "SessionCookie": "U2Vzc2lvbkNvb2tpZQ==",
    "InitialPlayers": ["gamer1", "gamer2"],
    "PreferredRegions": ["SouthCentralUs", "WestUs"]
}
headers = {
    "X-EntityToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-EntityToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    BuildId: '21781fa8-096d-4d9c-b699-75433d579285',
    SessionId: '02bdef0e-e01e-4b29-8efe-ff9f47a06d8c',
    SessionCookie: 'U2Vzc2lvbkNvb2tpZQ==',
    InitialPlayers: ['gamer1', 'gamer2'],
    PreferredRegions: ['SouthCentralUs', 'WestUs']
  })
};

fetch('https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer', 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://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'BuildId' => '21781fa8-096d-4d9c-b699-75433d579285',
    'SessionId' => '02bdef0e-e01e-4b29-8efe-ff9f47a06d8c',
    'SessionCookie' => 'U2Vzc2lvbkNvb2tpZQ==',
    'InitialPlayers' => [
        'gamer1',
        'gamer2'
    ],
    'PreferredRegions' => [
        'SouthCentralUs',
        'WestUs'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-EntityToken: <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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer"

	payload := strings.NewReader("{\n  \"BuildId\": \"21781fa8-096d-4d9c-b699-75433d579285\",\n  \"SessionId\": \"02bdef0e-e01e-4b29-8efe-ff9f47a06d8c\",\n  \"SessionCookie\": \"U2Vzc2lvbkNvb2tpZQ==\",\n  \"InitialPlayers\": [\n    \"gamer1\",\n    \"gamer2\"\n  ],\n  \"PreferredRegions\": [\n    \"SouthCentralUs\",\n    \"WestUs\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-EntityToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer")
  .header("X-EntityToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"BuildId\": \"21781fa8-096d-4d9c-b699-75433d579285\",\n  \"SessionId\": \"02bdef0e-e01e-4b29-8efe-ff9f47a06d8c\",\n  \"SessionCookie\": \"U2Vzc2lvbkNvb2tpZQ==\",\n  \"InitialPlayers\": [\n    \"gamer1\",\n    \"gamer2\"\n  ],\n  \"PreferredRegions\": [\n    \"SouthCentralUs\",\n    \"WestUs\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-EntityToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"BuildId\": \"21781fa8-096d-4d9c-b699-75433d579285\",\n  \"SessionId\": \"02bdef0e-e01e-4b29-8efe-ff9f47a06d8c\",\n  \"SessionCookie\": \"U2Vzc2lvbkNvb2tpZQ==\",\n  \"InitialPlayers\": [\n    \"gamer1\",\n    \"gamer2\"\n  ],\n  \"PreferredRegions\": [\n    \"SouthCentralUs\",\n    \"WestUs\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "SessionId": "02bdef0e-e01e-4b29-8efe-ff9f47a06d8c",
    "ServerId": "AMultiplayerGameServer",
    "VmId": "80c00b02-a559-4961-9b31-4a04b39e26a6",
    "IPV4Address": "10.250.24.54",
    "FQDN": "vm.azure.cloudapp.net",
    "Ports": [
      {
        "Name": "PortName",
        "Num": 1243
      }
    ],
    "Region": "SouthCentralUs",
    "State": "Active",
    "ConnectedPlayers": [
      {
        "PlayerId": "10931352888739351331"
      },
      {
        "PlayerId": "10271352123739051532"
      }
    ],
    "BuildId": "4da1a0f6-7e36-430c-a264-723ff6a605de"
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

Authorizations

X-EntityToken

string

header

required

This API requires an Entity Session Token, available from the Entity GetEntityToken method.

Body

application/json

Requests a multiplayer server session from a particular build in any of the given preferred regions.

PreferredRegions

enum<string>[]

required

The preferred regions to request a multiplayer server from. The Multiplayer Service will iterate through the regions in the specified order and allocate a server from the first one that has servers available.

Available options:

AustraliaEast,

AustraliaSoutheast,

BrazilSouth,

CentralUs,

EastAsia,

EastUs,

EastUs2,

JapanEast,

JapanWest,

NorthCentralUs,

NorthEurope,

SouthCentralUs,

SoutheastAsia,

WestEurope,

WestUs,

SouthAfricaNorth,

WestCentralUs,

KoreaCentral,

FranceCentral,

WestUs2,

CentralIndia,

UaeNorth,

UkSouth,

SwedenCentral,

CanadaCentral,

MexicoCentral,

WestUs3,

CanadaEast,

UkWest,

FranceSouth,

SouthIndia,

SpainCentral,

GermanyWestCentral,

ItalyNorth,

IndonesiaCentral,

ChileCentral,

PolandCentral,

NewZealandNorth,

BrazilSoutheast,

NorwayEast,

SwitzerlandNorth,

MalaysiaWest,

IsraelCentral,

QatarCentral,

UaeCentral,

GermanyNorth,

AustriaEast,

BelgiumCentral,

DenmarkEast,

SwitzerlandWest,

SwedenSouth,

NorwayWest,

SouthAfricaWest,

MalaysiaSouth

SessionId

string

required

A guid string session ID created track the multiplayer server session over its life.

BuildAliasParams

object

The identifiers of the build alias to use for the request.

Show child attributes

BuildId

string

The guid string build ID of the multiplayer server to request.

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

InitialPlayers

string[]

Initial list of players (potentially matchmade) allowed to connect to the game. This list is passed to the game server when requested (via GSDK) and can be used to validate players connecting to it.

Data encoded as a string that is passed to the game server when requested. This can be used to communicate information such as game mode or map through the request flow. Maximum size is 8KB

Response

code

integer

The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code.

status

string

The Http status code as a string.

data

object

Show child attributes

Example:

{
  "SessionId": "02bdef0e-e01e-4b29-8efe-ff9f47a06d8c",
  "ServerId": "AMultiplayerGameServer",
  "VmId": "80c00b02-a559-4961-9b31-4a04b39e26a6",
  "IPV4Address": "10.250.24.54",
  "FQDN": "vm.azure.cloudapp.net",
  "Ports": [{ "Name": "PortName", "Num": 1243 }],
  "Region": "SouthCentralUs",
  "State": "Active",
  "ConnectedPlayers": [
    { "PlayerId": "10931352888739351331" },
    { "PlayerId": "10271352123739051532" }
  ],
  "BuildId": "4da1a0f6-7e36-430c-a264-723ff6a605de"
}

Last modified on October 1, 2026

⌘I

Request Multiplayer Server

curl --request POST \
  --url https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer \
  --header 'Content-Type: application/json' \
  --header 'X-EntityToken: <api-key>' \
  --data '
{
  "BuildId": "21781fa8-096d-4d9c-b699-75433d579285",
  "SessionId": "02bdef0e-e01e-4b29-8efe-ff9f47a06d8c",
  "SessionCookie": "U2Vzc2lvbkNvb2tpZQ==",
  "InitialPlayers": [
    "gamer1",
    "gamer2"
  ],
  "PreferredRegions": [
    "SouthCentralUs",
    "WestUs"
  ]
}
'

import requests

url = "https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer"

payload = {
    "BuildId": "21781fa8-096d-4d9c-b699-75433d579285",
    "SessionId": "02bdef0e-e01e-4b29-8efe-ff9f47a06d8c",
    "SessionCookie": "U2Vzc2lvbkNvb2tpZQ==",
    "InitialPlayers": ["gamer1", "gamer2"],
    "PreferredRegions": ["SouthCentralUs", "WestUs"]
}
headers = {
    "X-EntityToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-EntityToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    BuildId: '21781fa8-096d-4d9c-b699-75433d579285',
    SessionId: '02bdef0e-e01e-4b29-8efe-ff9f47a06d8c',
    SessionCookie: 'U2Vzc2lvbkNvb2tpZQ==',
    InitialPlayers: ['gamer1', 'gamer2'],
    PreferredRegions: ['SouthCentralUs', 'WestUs']
  })
};

fetch('https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer', 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://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'BuildId' => '21781fa8-096d-4d9c-b699-75433d579285',
    'SessionId' => '02bdef0e-e01e-4b29-8efe-ff9f47a06d8c',
    'SessionCookie' => 'U2Vzc2lvbkNvb2tpZQ==',
    'InitialPlayers' => [
        'gamer1',
        'gamer2'
    ],
    'PreferredRegions' => [
        'SouthCentralUs',
        'WestUs'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-EntityToken: <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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer"

	payload := strings.NewReader("{\n  \"BuildId\": \"21781fa8-096d-4d9c-b699-75433d579285\",\n  \"SessionId\": \"02bdef0e-e01e-4b29-8efe-ff9f47a06d8c\",\n  \"SessionCookie\": \"U2Vzc2lvbkNvb2tpZQ==\",\n  \"InitialPlayers\": [\n    \"gamer1\",\n    \"gamer2\"\n  ],\n  \"PreferredRegions\": [\n    \"SouthCentralUs\",\n    \"WestUs\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-EntityToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer")
  .header("X-EntityToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"BuildId\": \"21781fa8-096d-4d9c-b699-75433d579285\",\n  \"SessionId\": \"02bdef0e-e01e-4b29-8efe-ff9f47a06d8c\",\n  \"SessionCookie\": \"U2Vzc2lvbkNvb2tpZQ==\",\n  \"InitialPlayers\": [\n    \"gamer1\",\n    \"gamer2\"\n  ],\n  \"PreferredRegions\": [\n    \"SouthCentralUs\",\n    \"WestUs\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/MultiplayerServer/RequestMultiplayerServer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-EntityToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"BuildId\": \"21781fa8-096d-4d9c-b699-75433d579285\",\n  \"SessionId\": \"02bdef0e-e01e-4b29-8efe-ff9f47a06d8c\",\n  \"SessionCookie\": \"U2Vzc2lvbkNvb2tpZQ==\",\n  \"InitialPlayers\": [\n    \"gamer1\",\n    \"gamer2\"\n  ],\n  \"PreferredRegions\": [\n    \"SouthCentralUs\",\n    \"WestUs\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "SessionId": "02bdef0e-e01e-4b29-8efe-ff9f47a06d8c",
    "ServerId": "AMultiplayerGameServer",
    "VmId": "80c00b02-a559-4961-9b31-4a04b39e26a6",
    "IPV4Address": "10.250.24.54",
    "FQDN": "vm.azure.cloudapp.net",
    "Ports": [
      {
        "Name": "PortName",
        "Num": 1243
      }
    ],
    "Region": "SouthCentralUs",
    "State": "Active",
    "ConnectedPlayers": [
      {
        "PlayerId": "10931352888739351331"
      },
      {
        "PlayerId": "10271352123739051532"
      }
    ],
    "BuildId": "4da1a0f6-7e36-430c-a264-723ff6a605de"
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

PlayFab API

PlayFab REST API References

Request Multiplayer Server

Error codes

Authorizations

Body

Response