Play Stream - Get Players In Segment

Service:

Admin

API Version:

250704

Allows for paging through all players in a given segment. This API creates a snapshot of all player profiles that match the segment definition at the time of its creation and lives through the Total Seconds to Live, refreshing its life span on each subsequent use of the Continuation Token. Profiles that change during the course of paging will not be reflected in the results. AB Test segments are currently not supported by this operation. NOTE: This API is limited to being called 30 times in one minute. You will be returned an error if you exceed this threshold.

POST https://titleId.playfabapi.com/Admin/GetPlayersInSegment

Request Header

Name	Required	Type	Description
X-SecretKey	True	string	This API requires a title secret key, available to title admins, from PlayFab Game Manager.

Request Body

Name	Required	Type	Description
SegmentId	True	string	Unique identifier for this segment.
ContinuationToken		string	Continuation token if retrieving subsequent pages of results.
CustomTags		object	The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
GetProfilesAsync		boolean	If set to true, the profiles are loaded asynchronously and the response will include a continuation token and approximate profile count until the first batch of profiles is loaded. Use this parameter to help avoid network timeouts.
MaxBatchSize		number	Maximum is 10,000. The value 0 will prevent loading any profiles and return only the count of profiles matching this segment.
SecondsToLive		number	Number of seconds to keep the continuation token active. After token expiration it is not possible to continue paging results. Default is 300 (5 minutes). Maximum is 5,400 (90 minutes).

Responses

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

Security

X-SecretKey

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

Type: apiKey
In: header

Definitions

Name	Description
AdCampaignAttribution
ApiErrorWrapper	The basic wrapper around every failed API response
ChurnRiskLevel
ContactEmailInfo
ContinentCode
CountryCode
EmailVerificationStatus
GetPlayersInSegmentRequest	Initial request must contain at least a Segment ID. Subsequent requests must contain the Segment ID as well as the Continuation Token. Failure to send the Continuation Token will result in a new player segment list being generated. Each time the Continuation Token is passed in the length of the Total Seconds to Live is refreshed. If too much time passes between requests to the point that a subsequent request is past the Total Seconds to Live an error will be returned and paging will be terminated. This API is resource intensive and should not be used in scenarios which might generate high request volumes. Only one request to this API at a time should be made per title. Concurrent requests to the API may be rejected with the APIConcurrentRequestLimitExceeded error.
GetPlayersInSegmentResult
LoginIdentityProvider
PlayerLinkedAccount
PlayerLocation
PlayerProfile
PlayerStatistic
PushNotificationPlatform
PushNotificationRegistration

AdCampaignAttribution

Object

Name	Type	Description
AttributedAt	string	UTC time stamp of attribution
CampaignId	string	Attribution campaign identifier
Platform	string	Attribution network name

ApiErrorWrapper

Object

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

ChurnRiskLevel

Enumeration

Value	Description
NoData
LowRisk
MediumRisk
HighRisk

ContactEmailInfo

Object

Name	Type	Description
EmailAddress	string	The email address
Name	string	The name of the email info data
VerificationStatus	EmailVerificationStatus	The verification status of the email

ContinentCode

Enumeration

Value	Description
AF
AN
AS
EU
NA
OC
SA
Unknown

CountryCode

Enumeration

Value	Description
AF
AX
AL
DZ
AS
AD
AO
AI
AQ
AG
AR
AM
AW
AU
AT
AZ
BS
BH
BD
BB
BY
BE
BZ
BJ
BM
BT
BO
BQ
BA
BW
BV
BR
IO
BN
BG
BF
BI
KH
CM
CA
CV
KY
CF
TD
CL
CN
CX
CC
CO
KM
CG
CD
CK
CR
CI
HR
CU
CW
CY
CZ
DK
DJ
DM
DO
EC
EG
SV
GQ
ER
EE
ET
FK
FO
FJ
FI
FR
GF
PF
TF
GA
GM
GE
DE
GH
GI
GR
GL
GD
GP
GU
GT
GG
GN
GW
GY
HT
HM
VA
HN
HK
HU
IS
IN
ID
IR
IQ
IE
IM
IL
IT
JM
JP
JE
JO
KZ
KE
KI
KP
KR
KW
KG
LA
LV
LB
LS
LR
LY
LI
LT
LU
MO
MK
MG
MW
MY
MV
ML
MT
MH
MQ
MR
MU
YT
MX
FM
MD
MC
MN
ME
MS
MA
MZ
MM
NA
NR
NP
NL
NC
NZ
NI
NE
NG
NU
NF
MP
NO
OM
PK
PW
PS
PA
PG
PY
PE
PH
PN
PL
PT
PR
QA
RE
RO
RU
RW
BL
SH
KN
LC
MF
PM
VC
WS
SM
ST
SA
SN
RS
SC
SL
SG
SX
SK
SI
SB
SO
ZA
GS
SS
ES
LK
SD
SR
SJ
SZ
SE
CH
SY
TW
TJ
TZ
TH
TL
TG
TK
TO
TT
TN
TR
TM
TC
TV
UG
UA
AE
GB
US
UM
UY
UZ
VU
VE
VN
VG
VI
WF
EH
YE
ZM
ZW
Unknown

EmailVerificationStatus

Enumeration

Value	Description
Unverified
Pending
Confirmed

GetPlayersInSegmentRequest

Object

Initial request must contain at least a Segment ID. Subsequent requests must contain the Segment ID as well as the Continuation Token. Failure to send the Continuation Token will result in a new player segment list being generated. Each time the Continuation Token is passed in the length of the Total Seconds to Live is refreshed. If too much time passes between requests to the point that a subsequent request is past the Total Seconds to Live an error will be returned and paging will be terminated. This API is resource intensive and should not be used in scenarios which might generate high request volumes. Only one request to this API at a time should be made per title. Concurrent requests to the API may be rejected with the APIConcurrentRequestLimitExceeded error.

Name	Type	Description
ContinuationToken	string	Continuation token if retrieving subsequent pages of results.
CustomTags	object	The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
GetProfilesAsync	boolean	If set to true, the profiles are loaded asynchronously and the response will include a continuation token and approximate profile count until the first batch of profiles is loaded. Use this parameter to help avoid network timeouts.
MaxBatchSize	number	Maximum is 10,000. The value 0 will prevent loading any profiles and return only the count of profiles matching this segment.
SecondsToLive	number	Number of seconds to keep the continuation token active. After token expiration it is not possible to continue paging results. Default is 300 (5 minutes). Maximum is 5,400 (90 minutes).
SegmentId	string	Unique identifier for this segment.

GetPlayersInSegmentResult

Object

Name	Type	Description
ContinuationToken	string	Continuation token to use to retrieve subsequent pages of results. If token returns null there are no more results.
PlayerProfiles	PlayerProfile[]	Array of player profiles in this segment.
ProfilesInSegment	number	Count of profiles matching this segment.

LoginIdentityProvider

Enumeration

Value	Description
Unknown
PlayFab
Custom
GameCenter
GooglePlay
Steam
XBoxLive
PSN
Kongregate
Facebook
IOSDevice
AndroidDevice
Twitch
WindowsHello
GameServer
CustomServer
NintendoSwitch
FacebookInstantGames
OpenIdConnect
Apple
NintendoSwitchAccount
GooglePlayGames
XboxMobileStore
King
BattleNet

PlayerLinkedAccount

Object

Name	Type	Description
Email	string	Linked account's email
Platform	LoginIdentityProvider	Authentication platform
PlatformUserId	string	Platform user identifier
Username	string	Linked account's username

PlayerLocation

Object

Name	Type	Description
City	string	City of the player's geographic location.
ContinentCode	ContinentCode	The two-character continent code for this location
CountryCode	CountryCode	The two-character ISO 3166-1 country code for the country associated with the location
Latitude	number	Latitude coordinate of the player's geographic location.
Longitude	number	Longitude coordinate of the player's geographic location.

PlayerProfile

Object

Name	Type	Description
AdCampaignAttributions	AdCampaignAttribution[]	Array of ad campaigns player has been attributed to
AvatarUrl	string	Image URL of the player's avatar.
BannedUntil	string	Banned until UTC Date. If permanent ban this is set for 20 years after the original ban date.
ChurnPrediction	ChurnRiskLevel	The prediction of the player to churn within the next seven days.
ContactEmailAddresses	ContactEmailInfo[]	Array of contact email addresses associated with the player
Created	string	Player record created
CustomProperties	object	Dictionary of player's custom properties.
DisplayName	string	Player Display Name
LastLogin	string	Last login
LinkedAccounts	PlayerLinkedAccount[]	Array of third party accounts linked to this player
Locations	PlayerLocation	Dictionary of player's locations by type.
Origination	LoginIdentityProvider	Player account origination
PlayerExperimentVariants	string[]	List of player variants for experimentation
PlayerId	string	PlayFab Player ID
PlayerStatistics	PlayerStatistic[]	Array of player statistics
PublisherId	string	Publisher this player belongs to
PushNotificationRegistrations	PushNotificationRegistration[]	Array of configured push notification end points
Statistics	object	Dictionary of player's statistics using only the latest version's value
Tags	string[]	List of player's tags for segmentation.
TitleId	string	Title ID this profile applies to
TotalValueToDateInUSD	number	A sum of player's total purchases in USD across all currencies.
ValuesToDate	object	Dictionary of player's total purchases by currency.
VirtualCurrencyBalances	object	Dictionary of player's virtual currency balances

PlayerStatistic

Object

Name	Type	Description
Id	string	Statistic ID
Name	string	Statistic name
StatisticValue	number	Current statistic value
StatisticVersion	number	Statistic version (0 if not a versioned statistic)

PushNotificationPlatform

Enumeration

Value	Description
ApplePushNotificationService
GoogleCloudMessaging

PushNotificationRegistration

Object

Name	Type	Description
NotificationEndpointARN	string	Notification configured endpoint
Platform	PushNotificationPlatform	Push notification platform

Error Codes

Name	Code
ExpiredContinuationToken	1241
GetPlayersInSegmentRateLimitExceeded	1491
InternalServerError	1110
InvalidContinuationToken	1240
InvalidSearchTerm	1245
InvalidSegment	1242
SegmentNotFound	1220