Create Experiment
Creates a new experiment for a title.
Allowed entity token types: title
Error codes
This operation may return the following PlayFab errors:
| Error | Code |
|---|---|
| ExperimentationExclusionGroupInsufficientCapacity | 7019 |
| ExperimentationExclusionGroupInvalidTrafficAllocation | 7021 |
| ExperimentationExclusionGroupNotFound | 7018 |
| ExperimentationInvalidEndDate | 7015 |
| ExperimentationInvalidStartDate | 7016 |
| ExperimentationMaxDurationExceeded | 7017 |
| FeatureNotConfiguredForTitle | 1177 |
| ProductDisabledForTitle | 1609 |
| SegmentNotFound | 1220 |
POST
/
Experimentation
/
CreateExperiment
Create Experiment
curl --request POST \
--url https://{titleId}.playfabapi.com/Experimentation/CreateExperiment \
--header 'Content-Type: application/json' \
--header 'X-EntityToken: <api-key>' \
--data '
{
"Name": "BackgroundColor Experiment",
"Description": "Tests whether a green background color increases revenue",
"StartDate": "2019-10-25T20:37:00Z",
"EndDate": "2019-11-13T20:37:00Z",
"Variants": [
{
"Name": "Control",
"Description": "Control variant",
"TrafficPercentage": 10,
"Variables": [
{
"Name": "BackgroundColor",
"Value": "White"
}
],
"IsControl": true
},
{
"Name": "Treatment",
"Description": "Treatment variant",
"TrafficPercentage": 90,
"Variables": [
{
"Name": "BackgroundColor",
"Value": "Green"
}
]
}
]
}
'import requests
url = "https://{titleId}.playfabapi.com/Experimentation/CreateExperiment"
payload = {
"Name": "BackgroundColor Experiment",
"Description": "Tests whether a green background color increases revenue",
"StartDate": "2019-10-25T20:37:00Z",
"EndDate": "2019-11-13T20:37:00Z",
"Variants": [
{
"Name": "Control",
"Description": "Control variant",
"TrafficPercentage": 10,
"Variables": [
{
"Name": "BackgroundColor",
"Value": "White"
}
],
"IsControl": True
},
{
"Name": "Treatment",
"Description": "Treatment variant",
"TrafficPercentage": 90,
"Variables": [
{
"Name": "BackgroundColor",
"Value": "Green"
}
]
}
]
}
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({
Name: 'BackgroundColor Experiment',
Description: 'Tests whether a green background color increases revenue',
StartDate: '2019-10-25T20:37:00Z',
EndDate: '2019-11-13T20:37:00Z',
Variants: [
{
Name: 'Control',
Description: 'Control variant',
TrafficPercentage: 10,
Variables: [{Name: 'BackgroundColor', Value: 'White'}],
IsControl: true
},
{
Name: 'Treatment',
Description: 'Treatment variant',
TrafficPercentage: 90,
Variables: [{Name: 'BackgroundColor', Value: 'Green'}]
}
]
})
};
fetch('https://{titleId}.playfabapi.com/Experimentation/CreateExperiment', 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/Experimentation/CreateExperiment",
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([
'Name' => 'BackgroundColor Experiment',
'Description' => 'Tests whether a green background color increases revenue',
'StartDate' => '2019-10-25T20:37:00Z',
'EndDate' => '2019-11-13T20:37:00Z',
'Variants' => [
[
'Name' => 'Control',
'Description' => 'Control variant',
'TrafficPercentage' => 10,
'Variables' => [
[
'Name' => 'BackgroundColor',
'Value' => 'White'
]
],
'IsControl' => true
],
[
'Name' => 'Treatment',
'Description' => 'Treatment variant',
'TrafficPercentage' => 90,
'Variables' => [
[
'Name' => 'BackgroundColor',
'Value' => 'Green'
]
]
]
]
]),
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/Experimentation/CreateExperiment"
payload := strings.NewReader("{\n \"Name\": \"BackgroundColor Experiment\",\n \"Description\": \"Tests whether a green background color increases revenue\",\n \"StartDate\": \"2019-10-25T20:37:00Z\",\n \"EndDate\": \"2019-11-13T20:37:00Z\",\n \"Variants\": [\n {\n \"Name\": \"Control\",\n \"Description\": \"Control variant\",\n \"TrafficPercentage\": 10,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"White\"\n }\n ],\n \"IsControl\": true\n },\n {\n \"Name\": \"Treatment\",\n \"Description\": \"Treatment variant\",\n \"TrafficPercentage\": 90,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"Green\"\n }\n ]\n }\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/Experimentation/CreateExperiment")
.header("X-EntityToken", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"Name\": \"BackgroundColor Experiment\",\n \"Description\": \"Tests whether a green background color increases revenue\",\n \"StartDate\": \"2019-10-25T20:37:00Z\",\n \"EndDate\": \"2019-11-13T20:37:00Z\",\n \"Variants\": [\n {\n \"Name\": \"Control\",\n \"Description\": \"Control variant\",\n \"TrafficPercentage\": 10,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"White\"\n }\n ],\n \"IsControl\": true\n },\n {\n \"Name\": \"Treatment\",\n \"Description\": \"Treatment variant\",\n \"TrafficPercentage\": 90,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"Green\"\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{titleId}.playfabapi.com/Experimentation/CreateExperiment")
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 \"Name\": \"BackgroundColor Experiment\",\n \"Description\": \"Tests whether a green background color increases revenue\",\n \"StartDate\": \"2019-10-25T20:37:00Z\",\n \"EndDate\": \"2019-11-13T20:37:00Z\",\n \"Variants\": [\n {\n \"Name\": \"Control\",\n \"Description\": \"Control variant\",\n \"TrafficPercentage\": 10,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"White\"\n }\n ],\n \"IsControl\": true\n },\n {\n \"Name\": \"Treatment\",\n \"Description\": \"Treatment variant\",\n \"TrafficPercentage\": 90,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"Green\"\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"status": "OK",
"data": {
"ExperimentId": "00000000-0000-0000-0000-000000000000"
}
}{
"code": 123,
"errorCode": 123,
"status": "<string>",
"error": "<string>",
"errorMessage": "<string>",
"errorDetails": {}
}Authorizations
This API requires an Entity Session Token, available from the Entity GetEntityToken method.
Body
application/json
Given a title entity token and experiment details, will create a new experiment for the title.
Given a title entity token and experiment details, will create a new experiment for the title.
Friendly name of the experiment.
When experiment should start.
List of variants for the experiment.
Show child attributes
Show child attributes
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
Description of the experiment.
When experiment should end.
Id of the exclusion group.
Percentage of exclusion group traffic that will see this experiment.
Type of experiment.
Available options:
Active, Snapshot Id of the segment to which this experiment applies. Defaults to the 'All Players' segment.
List of title player account IDs that automatically receive treatments in the experiment, but are not included when calculating experiment metrics.
Last modified on October 1, 2026
Was this page helpful?
⌘I
Create Experiment
curl --request POST \
--url https://{titleId}.playfabapi.com/Experimentation/CreateExperiment \
--header 'Content-Type: application/json' \
--header 'X-EntityToken: <api-key>' \
--data '
{
"Name": "BackgroundColor Experiment",
"Description": "Tests whether a green background color increases revenue",
"StartDate": "2019-10-25T20:37:00Z",
"EndDate": "2019-11-13T20:37:00Z",
"Variants": [
{
"Name": "Control",
"Description": "Control variant",
"TrafficPercentage": 10,
"Variables": [
{
"Name": "BackgroundColor",
"Value": "White"
}
],
"IsControl": true
},
{
"Name": "Treatment",
"Description": "Treatment variant",
"TrafficPercentage": 90,
"Variables": [
{
"Name": "BackgroundColor",
"Value": "Green"
}
]
}
]
}
'import requests
url = "https://{titleId}.playfabapi.com/Experimentation/CreateExperiment"
payload = {
"Name": "BackgroundColor Experiment",
"Description": "Tests whether a green background color increases revenue",
"StartDate": "2019-10-25T20:37:00Z",
"EndDate": "2019-11-13T20:37:00Z",
"Variants": [
{
"Name": "Control",
"Description": "Control variant",
"TrafficPercentage": 10,
"Variables": [
{
"Name": "BackgroundColor",
"Value": "White"
}
],
"IsControl": True
},
{
"Name": "Treatment",
"Description": "Treatment variant",
"TrafficPercentage": 90,
"Variables": [
{
"Name": "BackgroundColor",
"Value": "Green"
}
]
}
]
}
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({
Name: 'BackgroundColor Experiment',
Description: 'Tests whether a green background color increases revenue',
StartDate: '2019-10-25T20:37:00Z',
EndDate: '2019-11-13T20:37:00Z',
Variants: [
{
Name: 'Control',
Description: 'Control variant',
TrafficPercentage: 10,
Variables: [{Name: 'BackgroundColor', Value: 'White'}],
IsControl: true
},
{
Name: 'Treatment',
Description: 'Treatment variant',
TrafficPercentage: 90,
Variables: [{Name: 'BackgroundColor', Value: 'Green'}]
}
]
})
};
fetch('https://{titleId}.playfabapi.com/Experimentation/CreateExperiment', 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/Experimentation/CreateExperiment",
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([
'Name' => 'BackgroundColor Experiment',
'Description' => 'Tests whether a green background color increases revenue',
'StartDate' => '2019-10-25T20:37:00Z',
'EndDate' => '2019-11-13T20:37:00Z',
'Variants' => [
[
'Name' => 'Control',
'Description' => 'Control variant',
'TrafficPercentage' => 10,
'Variables' => [
[
'Name' => 'BackgroundColor',
'Value' => 'White'
]
],
'IsControl' => true
],
[
'Name' => 'Treatment',
'Description' => 'Treatment variant',
'TrafficPercentage' => 90,
'Variables' => [
[
'Name' => 'BackgroundColor',
'Value' => 'Green'
]
]
]
]
]),
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/Experimentation/CreateExperiment"
payload := strings.NewReader("{\n \"Name\": \"BackgroundColor Experiment\",\n \"Description\": \"Tests whether a green background color increases revenue\",\n \"StartDate\": \"2019-10-25T20:37:00Z\",\n \"EndDate\": \"2019-11-13T20:37:00Z\",\n \"Variants\": [\n {\n \"Name\": \"Control\",\n \"Description\": \"Control variant\",\n \"TrafficPercentage\": 10,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"White\"\n }\n ],\n \"IsControl\": true\n },\n {\n \"Name\": \"Treatment\",\n \"Description\": \"Treatment variant\",\n \"TrafficPercentage\": 90,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"Green\"\n }\n ]\n }\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/Experimentation/CreateExperiment")
.header("X-EntityToken", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"Name\": \"BackgroundColor Experiment\",\n \"Description\": \"Tests whether a green background color increases revenue\",\n \"StartDate\": \"2019-10-25T20:37:00Z\",\n \"EndDate\": \"2019-11-13T20:37:00Z\",\n \"Variants\": [\n {\n \"Name\": \"Control\",\n \"Description\": \"Control variant\",\n \"TrafficPercentage\": 10,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"White\"\n }\n ],\n \"IsControl\": true\n },\n {\n \"Name\": \"Treatment\",\n \"Description\": \"Treatment variant\",\n \"TrafficPercentage\": 90,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"Green\"\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{titleId}.playfabapi.com/Experimentation/CreateExperiment")
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 \"Name\": \"BackgroundColor Experiment\",\n \"Description\": \"Tests whether a green background color increases revenue\",\n \"StartDate\": \"2019-10-25T20:37:00Z\",\n \"EndDate\": \"2019-11-13T20:37:00Z\",\n \"Variants\": [\n {\n \"Name\": \"Control\",\n \"Description\": \"Control variant\",\n \"TrafficPercentage\": 10,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"White\"\n }\n ],\n \"IsControl\": true\n },\n {\n \"Name\": \"Treatment\",\n \"Description\": \"Treatment variant\",\n \"TrafficPercentage\": 90,\n \"Variables\": [\n {\n \"Name\": \"BackgroundColor\",\n \"Value\": \"Green\"\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"status": "OK",
"data": {
"ExperimentId": "00000000-0000-0000-0000-000000000000"
}
}{
"code": 123,
"errorCode": 123,
"status": "<string>",
"error": "<string>",
"errorMessage": "<string>",
"errorDetails": {}
}