Share via

Play Stream - Get Players In Segment

  • Reference
Service:
Server
API Version:
241122

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/Server/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

Name Type Description
AttributedAt

string

UTC time stamp of attribution
CampaignId

string

Attribution campaign identifier
Platform

string

Attribution network name

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

ChurnRiskLevel

Name Type Description
HighRisk

string

LowRisk

string

MediumRisk

string

NoData

string

ContactEmailInfo

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

Name Type Description
AF

string

AN

string

AS

string

EU

string

NA

string

OC

string

SA

string

Unknown

string

CountryCode

Name Type Description
AD

string

AE

string

AF

string

AG

string

AI

string

AL

string

AM

string

AO

string

AQ

string

AR

string

AS

string

AT

string

AU

string

AW

string

AX

string

AZ

string

BA

string

BB

string

BD

string

BE

string

BF

string

BG

string

BH

string

BI

string

BJ

string

BL

string

BM

string

BN

string

BO

string

BQ

string

BR

string

BS

string

BT

string

BV

string

BW

string

BY

string

BZ

string

CA

string

CC

string

CD

string

CF

string

CG

string

CH

string

CI

string

CK

string

CL

string

CM

string

CN

string

CO

string

CR

string

CU

string

CV

string

CW

string

CX

string

CY

string

CZ

string

DE

string

DJ

string

DK

string

DM

string

DO

string

DZ

string

EC

string

EE

string

EG

string

EH

string

ER

string

ES

string

ET

string

FI

string

FJ

string

FK

string

FM

string

FO

string

FR

string

GA

string

GB

string

GD

string

GE

string

GF

string

GG

string

GH

string

GI

string

GL

string

GM

string

GN

string

GP

string

GQ

string

GR

string

GS

string

GT

string

GU

string

GW

string

GY

string

HK

string

HM

string

HN

string

HR

string

HT

string

HU

string

ID

string

IE

string

IL

string

IM

string

IN

string

IO

string

IQ

string

IR

string

IS

string

IT

string

JE

string

JM

string

JO

string

JP

string

KE

string

KG

string

KH

string

KI

string

KM

string

KN

string

KP

string

KR

string

KW

string

KY

string

KZ

string

LA

string

LB

string

LC

string

LI

string

LK

string

LR

string

LS

string

LT

string

LU

string

LV

string

LY

string

MA

string

MC

string

MD

string

ME

string

MF

string

MG

string

MH

string

MK

string

ML

string

MM

string

MN

string

MO

string

MP

string

MQ

string

MR

string

MS

string

MT

string

MU

string

MV

string

MW

string

MX

string

MY

string

MZ

string

NA

string

NC

string

NE

string

NF

string

NG

string

NI

string

NL

string

NO

string

NP

string

NR

string

NU

string

NZ

string

OM

string

PA

string

PE

string

PF

string

PG

string

PH

string

PK

string

PL

string

PM

string

PN

string

PR

string

PS

string

PT

string

PW

string

PY

string

QA

string

RE

string

RO

string

RS

string

RU

string

RW

string

SA

string

SB

string

SC

string

SD

string

SE

string

SG

string

SH

string

SI

string

SJ

string

SK

string

SL

string

SM

string

SN

string

SO

string

SR

string

SS

string

ST

string

SV

string

SX

string

SY

string

SZ

string

TC

string

TD

string

TF

string

TG

string

TH

string

TJ

string

TK

string

TL

string

TM

string

TN

string

TO

string

TR

string

TT

string

TV

string

TW

string

TZ

string

UA

string

UG

string

UM

string

US

string

UY

string

UZ

string

Unknown

string

VA

string

VC

string

VE

string

VG

string

VI

string

VN

string

VU

string

WF

string

WS

string

YE

string

YT

string

ZA

string

ZM

string

ZW

string

EmailVerificationStatus

Name Type Description
Confirmed

string

Pending

string

Unverified

string

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.

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

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

Name Type Description
AndroidDevice

string

Apple

string

Custom

string

CustomServer

string

Facebook

string

FacebookInstantGames

string

GameCenter

string

GameServer

string

GooglePlay

string

GooglePlayGames

string

IOSDevice

string

King

string

Kongregate

string

NintendoSwitch

string

NintendoSwitchAccount

string

OpenIdConnect

string

PSN

string

PlayFab

string

Steam

string

Twitch

string

Unknown

string

WindowsHello

string

XBoxLive

string

XboxMobileStore

string

PlayerLinkedAccount

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

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

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
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

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

Name Type Description
ApplePushNotificationService

string

GoogleCloudMessaging

string

PushNotificationRegistration

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