Create Player Statistic Definition

Adds a new player statistic configuration to the title, optionally allowing the developer to specify a reset interval and an aggregation method.

Error codes

This operation may return the following PlayFab errors:

Error	Code
ProductDisabledForTitle	1609
StatisticCountLimitExceeded	1203
StatisticNameConflict	1196

POST

Admin

CreatePlayerStatisticDefinition

Create Player Statistic Definition

curl --request POST \
  --url https://{titleId}.playfabapi.com/Admin/CreatePlayerStatisticDefinition \
  --header 'Content-Type: application/json' \
  --header 'X-SecretKey: <api-key>' \
  --data '
{
  "StatisticName": "headshots",
  "VersionChangeInterval": "Never"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Admin/CreatePlayerStatisticDefinition"

payload = {
    "StatisticName": "headshots",
    "VersionChangeInterval": "Never"
}
headers = {
    "X-SecretKey": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-SecretKey': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({StatisticName: 'headshots', VersionChangeInterval: 'Never'})
};

fetch('https://{titleId}.playfabapi.com/Admin/CreatePlayerStatisticDefinition', 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/Admin/CreatePlayerStatisticDefinition",
  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([
    'StatisticName' => 'headshots',
    'VersionChangeInterval' => 'Never'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-SecretKey: <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/Admin/CreatePlayerStatisticDefinition"

	payload := strings.NewReader("{\n  \"StatisticName\": \"headshots\",\n  \"VersionChangeInterval\": \"Never\"\n}")

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

	req.Header.Add("X-SecretKey", "<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/Admin/CreatePlayerStatisticDefinition")
  .header("X-SecretKey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"StatisticName\": \"headshots\",\n  \"VersionChangeInterval\": \"Never\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Admin/CreatePlayerStatisticDefinition")

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

request = Net::HTTP::Post.new(url)
request["X-SecretKey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"StatisticName\": \"headshots\",\n  \"VersionChangeInterval\": \"Never\"\n}"

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

{
  "code": 200,
  "status": "OK",
  "data": {
    "Statistic": {
      "StatisticName": "headshots",
      "CurrentVersion": 2,
      "VersionChangeInterval": "Day"
    }
  }
}

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

Authorizations

X-SecretKey

string

header

required

This API requires a title secret key, available to title admins, from PlayFab Game Manager.

Body

application/json

Statistics are numeric values, with each statistic in the title also generating a leaderboard. The ResetInterval enables automatically resetting leaderboards on a specified interval. Upon reset, the statistic updates to a new version with no values (effectively removing all players from the leaderboard). The previous version's statistic values are also archived for retrieval, if needed (see GetPlayerStatisticVersions). Statistics not created via a call to CreatePlayerStatisticDefinition by default have a VersionChangeInterval of Never, meaning they do not reset on a schedule, but they can be set to do so via a call to UpdatePlayerStatisticDefinition. Once a statistic has been reset (sometimes referred to as versioned or incremented), the now-previous version can still be written to for up a short, pre-defined period (currently 10 seconds), to prevent issues with levels completing around the time of the reset. Also, once reset, the historical statistics for players in the title may be retrieved using the URL specified in the version information (GetPlayerStatisticVersions). The AggregationMethod determines what action is taken when a new statistic value is submitted - always update with the new value (Last), use the highest of the old and new values (Max), use the smallest (Min), or add them together (Sum).

StatisticName

string

required

unique name of the statistic

AggregationMethod

enum<string>

the aggregation method to use in updating the statistic (defaults to last)

Available options:

Last,

Min,

Max,

Sum

CustomTags

object

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

VersionChangeInterval

enum<string>

interval at which the values of the statistic for all players are reset (resets begin at the next interval boundary)

Available options:

Never,

Hour,

Day,

Week,

Month

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:

{
  "Statistic": {
    "StatisticName": "headshots",
    "CurrentVersion": 2,
    "VersionChangeInterval": "Day"
  }
}

Last modified on October 1, 2026

⌘I

Create Player Statistic Definition

curl --request POST \
  --url https://{titleId}.playfabapi.com/Admin/CreatePlayerStatisticDefinition \
  --header 'Content-Type: application/json' \
  --header 'X-SecretKey: <api-key>' \
  --data '
{
  "StatisticName": "headshots",
  "VersionChangeInterval": "Never"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Admin/CreatePlayerStatisticDefinition"

payload = {
    "StatisticName": "headshots",
    "VersionChangeInterval": "Never"
}
headers = {
    "X-SecretKey": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-SecretKey': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({StatisticName: 'headshots', VersionChangeInterval: 'Never'})
};

fetch('https://{titleId}.playfabapi.com/Admin/CreatePlayerStatisticDefinition', 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/Admin/CreatePlayerStatisticDefinition",
  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([
    'StatisticName' => 'headshots',
    'VersionChangeInterval' => 'Never'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-SecretKey: <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/Admin/CreatePlayerStatisticDefinition"

	payload := strings.NewReader("{\n  \"StatisticName\": \"headshots\",\n  \"VersionChangeInterval\": \"Never\"\n}")

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

	req.Header.Add("X-SecretKey", "<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/Admin/CreatePlayerStatisticDefinition")
  .header("X-SecretKey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"StatisticName\": \"headshots\",\n  \"VersionChangeInterval\": \"Never\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Admin/CreatePlayerStatisticDefinition")

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

request = Net::HTTP::Post.new(url)
request["X-SecretKey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"StatisticName\": \"headshots\",\n  \"VersionChangeInterval\": \"Never\"\n}"

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

{
  "code": 200,
  "status": "OK",
  "data": {
    "Statistic": {
      "StatisticName": "headshots",
      "CurrentVersion": 2,
      "VersionChangeInterval": "Day"
    }
  }
}

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

PlayFab API

PlayFab REST API References

Create Player Statistic Definition

Error codes

Authorizations

Body

Response