Statistics - Update Statistics

Service:

Progression

API Version:

241122

Update statistics on an entity profile. Depending on the statistic definition, this may result in entity being ranked on various leaderboards.

POST https://titleId.playfabapi.com/Statistic/UpdateStatistics

Request Header

Name	Required	Type	Description
X-EntityToken	True	string	This API requires an Entity Session Token, available from the Entity GetEntityToken method.

Request Body

Name	Required	Type	Description
Statistics	True	StatisticUpdate[]	Collection of statistics to update, maximum 50.
CustomTags		object	The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
Entity		EntityKey	The optional entity to perform this action on. Defaults to the currently logged in entity.

Responses

Name	Type	Description
200 OK	UpdateStatisticsResponse
400 Bad Request	ApiErrorWrapper	This is the outer wrapper for all responses with errors

Security

X-EntityToken

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

Type: apiKey
In: header

Definitions

Name	Description
ApiErrorWrapper	The basic wrapper around every failed API response
EntityKey	Combined entity type and ID structure which uniquely identifies a single entity.
EntityStatisticValue
StatisticAggregationMethod
StatisticColumn
StatisticColumnCollection
StatisticUpdate
UpdateStatisticsRequest
UpdateStatisticsResponse

ApiErrorWrapper

The basic wrapper around every failed API response

Name	Type	Description
code	integer	Numerical HTTP code
error	string	Playfab error code
errorCode	integer	Numerical PlayFab error code
errorDetails	object	Detailed description of individual issues with the request object
errorMessage	string	Description for the PlayFab errorCode
status	string	String HTTP code

EntityKey

Combined entity type and ID structure which uniquely identifies a single entity.

Name	Type	Description
Id	string	Unique ID of the entity.
Type	string	Entity type. See https://docs.microsoft.com/gaming/playfab/features/data/entities/available-built-in-entity-types

EntityStatisticValue

Name	Type	Description
Metadata	string	Metadata associated with the Statistic.
Name	string	Statistic name
Scores	string[]	Statistic scores
Version	number	Statistic version

StatisticAggregationMethod

Name	Type	Description
Last	string
Max	string
Min	string
Sum	string

StatisticColumn

Name	Type	Description
AggregationMethod	StatisticAggregationMethod	Aggregation method for calculating new value of a statistic.
Name	string	Name of the statistic column, as originally configured.

StatisticColumnCollection

Name	Type	Description
Columns	StatisticColumn[]	Columns for the statistic defining the aggregation method for each column.

StatisticUpdate

Name	Type	Description
Metadata	string	Arbitrary metadata to store along side the statistic, will be returned by all Leaderboard APIs. Must be less than 50 UTF8 encoded characters.
Name	string	Name of the statistic, as originally configured.
Scores	string[]	Statistic scores for the entity. This will be used in accordance with the aggregation method configured for the statistics.The maximum value allowed for each individual score is 9223372036854775807. The minimum value for each individual score is -9223372036854775807The values are formatted as strings to avoid interop issues with client libraries unable to handle 64bit integers.
Version	number	Optional field to indicate the version of the statistic to set. When empty defaults to the statistic's current version.

UpdateStatisticsRequest

Name	Type	Description
CustomTags	object	The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
Entity	EntityKey	The optional entity to perform this action on. Defaults to the currently logged in entity.
Statistics	StatisticUpdate[]	Collection of statistics to update, maximum 50.

UpdateStatisticsResponse

Name	Type	Description
ColumnDetails	StatisticColumnCollection	A mapping of statistic name to the columns defined in the corresponding definition.
Entity	EntityKey	The entity id and type.
Statistics	EntityStatisticValue	Updated entity profile statistics.

Error Codes

Name	Code
APINotEnabledForGameClientAccess	1082
EntityTypeMismatchWithStatDefinition	1582
InvalidEntityType	1373
NotAuthorized	1089
StatisticColumnLengthMismatch	1593
StatisticNotFound	1195
TransactionAlreadyApplied	1596