GearN Server | Rest Api references | Game Player

Overview

List all players who have been assigned a specific tag.

Client

Require permission rules gamePlayer.getPlayersWithTag.selfEnable. See PermissionRules

HTTP

POST /api/rJson/gamePlayer/client/getPlayersWithTag

Request Headers

Name	Type	Required	Description
Auth-Token	string	true	A token used to authenticate the user. It is issued after successful login from the client type authenticate (e.g., loginByAccount, loginWithCustomId, etc.) or when an admin logs in via the GearN Dashboard. This token identifies the request sender and determines their access level.
Secret-Key	string	true	The SecretKey in SecretInfo with role must is Player.
Game-Id	string		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	string	true	application/json

Request Body

Code	Type	Required	Description
key	string	true	Key parameter. (2 - 32 characters)
value	string	true	String value representing the name or identifier of a segment or tag. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	InfoRequestParam parameter. See InfoRequestParam
skip	number int		Skip parameter. (from 0) (Default: 0)
limit	number int		Limit parameter. (from 1 to 100) (Default: 10)

Server

Require permission rules gamePlayer.getPlayersWithTag.serverSelfEnable. See PermissionRules

HTTP

POST /api/rJson/gamePlayer/server/getPlayersWithTag

Request Headers

Name	Type	Required	Description
Secret-Key	string	true	The SecretKey in SecretInfo with role must is Admin.
Game-Id	string		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	string	true	application/json

Request Body

Code	Type	Required	Description
key	string	true	Key parameter. (2 - 32 characters)
value	string	true	String value representing the name or identifier of a segment or tag. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	InfoRequestParam parameter. See InfoRequestParam
skip	number int		Skip parameter. (from 0) (Default: 0)
limit	number int		Limit parameter. (from 1 to 100) (Default: 10)

Admin

Require permission rules gamePlayer.getPlayersWithTag.adminSelfEnable. See PermissionRules

HTTP

POST /api/rJson/gamePlayer/admin/getPlayersWithTag

Request Headers

Name	Type	Required	Description
Secret-Key	string	true	The SecretKey in SecretInfo with role must is Admin.
Game-Id	string		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	string	true	application/json

Request Body

Code	Type	Required	Description
key	string	true	Key parameter. (2 - 32 characters)
value	string	true	String value representing the name or identifier of a segment or tag. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	InfoRequestParam parameter. See InfoRequestParam
skip	number int		Skip parameter. (from 0) (Default: 0)
limit	number int		Limit parameter. (from 1 to 100) (Default: 10)

Response Body

200 Ok

Code	Type	Required	Description
returnCode	ReturnCode	true	Additional metadata that can be attached to any request. Especially useful when working with advanced features such as EventCallbackScript. See ReturnCode
debugMessage	string		A developer-oriented message that provides additional context useful for debugging and internal logging. This field is not intended for end-users and may include stack traces, validation failures, or internal error diagnostics.
invalidRequestParameters	InvalidMember[]		Just had data when the returnCode is InvalidRequestParameters.A list of members that failed validation or could not be processed during the request. Each entry typically includes identifying information and an error reason. This is useful for partial success scenarios where some members are accepted and others are rejected. See InvalidMember
parameters	ResponseData		Just had data when the returnCode is Ok. A dynamic set of key-value pairs included in the response to provide additional context or metadata. These parameters may vary depending on the operation and typically contain optional fields such as timestamps, identifiers, or computed values relevant to the result. See ResponseData

ReturnCode

Name	Code	Description
SecretInvalid	-10	The selected secret key is missing, wrong, or does not match the current route/game context.
MaxSizeRequestReject	-9	The serialized request payload exceeded the maximum size accepted by the backend.
MaxRequestReject	-8	The backend rejected the request because the current caller exceeded a request-rate limit.
MaxCCUReject	-7	The backend rejected the request because the current concurrent-user/session limit was exceeded.
OperationNotAuthorized	-6	The target operation exists, but the caller is not authorized for the selected role or target resource.
InvalidRequestParameters	-5	The request shape or one or more request-member values are invalid. When available, inspect `invalidMembers` for field-level details.
OperationInvalid	-4	The requested operation code is unknown or is not valid for the selected request type/role.
InternalServerError	-3	The backend hit an unhandled internal failure before producing a valid business response.
OperationNotAllow	-2	The operation is known and the secret key is valid, but the permission rules attached to the current secret key do not allow this operation in the current target context. This usually maps to missing `selfEnable`, `otherSelfEnable`, `serverSelfEnable`, or `adminSelfEnable` permission for the resolved request.
OperationTimeout	-1	The request timed out before a response was received. This code may be synthesized by the SDK timeout layer as well as returned by the backend.
UnknownError	0	The request failed, but no more specific low-level return code was mapped.
Ok	1	The request completed successfully at protocol level and produced a response payload. Callers must still validate the business `errorCode` in that payload.

ResponseData

Code	Type	Required	Description
errorCode	ErrorCode		A string that represents the status of the operation. It indicates whether the request was successful or failed due to a specific error condition. See ErrorCode
results	GamePlayerWithUserIdResponseData[]	true	Results field in model GamePlayersWithUserIdResponseData. See GamePlayerWithUserIdResponseData

InfoRequestParam

Defines which optional fields should be included in player information responses.

Code	Type	Description
segments	boolean	Include player segment information in the response. (Default: false)
customDatas	boolean	Include key-value custom data fields in the response. (Default: false)
displayName	boolean	Include the player's display name in the response. (Default: false)
avatar	boolean	Include the player's avatar URL or image reference. (Default: false)
tsCreate	boolean	Include the timestamp when the player account was created. (Default: false)
tags	boolean	Include tags assigned to the player. (Default: false)
playerBan	boolean	Include any ban status information in the response. (Default: false)
playerCurrencies	boolean	Include the player's virtual currency balances. (Default: false)
playerStatistics	boolean	Include the player's statistics. (Default: false)
playerDatas	boolean	PlayerDatas field in model InfoRequestParam. (Default: false)
ipAddressCreate	boolean	IpAddressCreate field in model InfoRequestParam. (Default: false)
countryCode	boolean	CountryCode field in model InfoRequestParam. (Default: false)
onlineStatus	boolean	Online status field in model InfoRequestParam. (Default: false)
tsLastLogin	boolean	TsLastLogin field in model InfoRequestParam. (Default: false)
playerCharacters	boolean	PlayerCharacters field in model InfoRequestParam. (Default: false)
playerInventories	boolean	PlayerInventories field in model InfoRequestParam. (Default: false)
playerGroups	boolean	PlayerGroups field in model InfoRequestParam. (Default: false)
playerFriends	boolean	PlayerFriends field in model InfoRequestParam. (Default: false)
playerDataKeys	string[]	PlayerDataKeys field in model InfoRequestParam.
playerCurrencyKeys	string[]	PlayerCurrencyKeys field in model InfoRequestParam.
playerStatisticsKeys	string[]	PlayerStatisticsKeys field in model InfoRequestParam.
customDataKeys	string[]	CustomDataKeys field in model InfoRequestParam.
tagKeys	string[]	TagKeys field in model InfoRequestParam.
characterCatalogIds	string[]	CharacterCatalogIds field in model InfoRequestParam.
itemCatalogIds	string[]	ItemCatalogIds field in model InfoRequestParam.
groupCatalogIds	string[]	GroupCatalogIds field in model InfoRequestParam.
friendCatalogIds	string[]	FriendCatalogIds field in model InfoRequestParam.

GamePlayerWithUserIdResponseData

Player profile data returned using a UserId-based query.

Code	Type	Required	Description
userId	string	true	Unique identifier of the player targeted by the operation.
infoResponseParameters	InfoResponseParameters	true	InfoResponseParameters field in model GamePlayerWithUserIdResponseData. See InfoResponseParameters

InfoResponseParameters

Contains optional metadata fields returned when requesting player info.

Code	Type	Description
segments	string[]	Include player segment information in the response.
customDatas	GenericModels.DataItem[]	Include key-value custom data fields in the response. See GenericModels.DataItem
displayName	string	Include the player's display name in the response.
avatar	GenericModels.AvatarItem	Include the player's avatar URL or image reference. See GenericModels.AvatarItem
tsCreate	number	Include the timestamp when the player account was created.
tags	GenericModels.TagItem[]	Include tags assigned to the player. See GenericModels.TagItem
playerBan	GenericModels.BanItem	Include any ban status information in the response. See GenericModels.BanItem
playerDatas	GenericModels.DataItem[]	PlayerDatas field in model InfoResponseParameters. See GenericModels.DataItem
playerCurrencies	GenericModels.CurrencyItem[]	Include the player's virtual currency balances. See GenericModels.CurrencyItem
playerStatistics	GenericModels.StatisticsItem[]	Include the player's statistics. See GenericModels.StatisticsItem
playerCharacters	GenericModels.CharacterItem[]	PlayerCharacters field in model InfoResponseParameters. See GenericModels.CharacterItem
playerInventories	GenericModels.InventoryItem[]	PlayerInventories field in model InfoResponseParameters. See GenericModels.InventoryItem
playerGroups	GenericModels.GroupItem[]	PlayerGroups field in model InfoResponseParameters. See GenericModels.GroupItem
playerFriends	GenericModels.FriendItem[]	PlayerFriends field in model InfoResponseParameters. See GenericModels.FriendItem
tsLastLogin	number	TsLastLogin field in model InfoResponseParameters.
ipAddressCreate	string	IpAddressCreate field in model InfoResponseParameters.
countryCode	string	CountryCode field in model InfoResponseParameters.
onlineStatus	OnlineStatusItem	Online status field in model InfoResponseParameters. See OnlineStatusItem

Generic.DataItem

Represents an arbitrary key-value data entry.

Code	Type	Required	Description
key	string	true	Data entry key used to identify the payload.
value	any	true	Raw value returned by the backend. This may be a primitive, `GNHashtable`, `GNArray`, or plain object-like data.

Generic.AvatarItem

Represents a generic avatar payload.

Code	Type	Required	Description
type	number	true	Backend-defined avatar type identifier. The public SDK currently does not export a dedicated avatar enum.
value	string	true	Avatar value, typically a URL, file id, or provider-specific string.

Generic.TagItem

Represents a key-value tag entry.

Code	Type	Required	Description
key	string	true	Tag key used to identify the metadata entry.
value	string	true	Tag value associated with `key`.

Generic.BanItem

Represents a ban state entry returned by player-auth or player-profile flows.

Code	Type	Required	Description
tsExpire	number	true	Expiration timestamp of the current ban state. -1 is never unban.
reason	string	true	Human-readable ban reason when provided by the backend.

Generic.CurrencyItem

Represents one currency entry.

Code	Type	Required	Description
key	string	true	Currency key such as the configured currency code or logical name.
value	number	true	Numeric balance of the currency identified by `key`.

Generic.StatisticsItem

Represents one statistics entry.

Code	Type	Required	Description
key	string	true	Statistic key such as the configured metric name.
value	number	true	Numeric value of the statistic identified by `key`.

Generic.CharacterItem

Represents a lightweight relation item pointing to a character.

Code	Type	Required	Description
characterId	string	true	Character identifier of the related character entity.
catalogId	string	true	Catalog identifier associated with the related character.

Generic.InventoryItem

Represents a lightweight relation item pointing to an inventory item.

Code	Type	Required	Description
itemId	string	true	Inventory item identifier of the related item entity.
catalogId	string	true	Catalog identifier associated with the related inventory item.
classId	string	true	Class identifier associated with the related inventory item.

Generic.GroupItem

Represents a lightweight relation item pointing to a group.

Code	Type	Required	Description
groupId	string	true	Group identifier of the related group entity.
catalogId	string	true	Catalog identifier associated with the related group.
status	number	true	Group relation status. Map this value with the public `GroupStatus` enum.
tsLastStatusUpdate	number	true	Timestamp of the last group status change.

Generic.FriendItem

Represents a lightweight relation item pointing to a friend relation.

Code	Type	Required	Description
friendId	string	true	Friend identifier of the related friend entity.
catalogId	string	true	Catalog identifier associated with the related friend entity.
status	number	true	Friend relation status. Map this value with the public `FriendStatus` enum.
tsLastStatusUpdate	number	true	Timestamp of the last friend status change.

OnlineStatusItem

Online/offline status and session metadata for a player.

Code	Type	Required	Description
tsLastLogin	number	true	TsLastLogin field in model OnlineStatusItem.
socketId	string	true	SocketId field in model OnlineStatusItem.

ErrorCode

Name	Code	Description
Ok	1	The business operation completed successfully.
KeyNotFound	9	The requested key does not exist in the target data set.

InvalidMember

Code	Type	Description
code	string	The parameterCode invalid.
invalidMemberType	InvalidMemberType	The invalid member type of this parameterCode. See InvalidMemberType

InvalidMemberType

Name	Code	Description
UnknownError	1	The backend rejected the member but did not map it to a more specific validation category.
DataRequired	2	The member is required but missing.
TypeInvalid	3	The member type does not match the expected runtime type.
StringNull	4	A required string member is null or empty when null is not allowed.
StringMinLength	5	A string member is shorter than the configured minimum length.
StringMaxLength	6	A string member is longer than the configured maximum length.
NumberMinValue	7	A numeric member is lower than the configured minimum value.
NumberMaxValue	8	A numeric member is higher than the configured maximum value.
NumberMustInt	9	A numeric member must be an integer but received a non-integer value.
GNHashtableNull	10	A required `GNHashtable` member is null.
GNHashtableMinLength	11	A `GNHashtable` member contains fewer entries than allowed.
GNHashtableMaxLength	12	A `GNHashtable` member contains more entries than allowed.
GNArrayNull	13	A required `GNArray` member is null.
GNArrayMinLength	14	A `GNArray` member contains fewer items than allowed.
GNArrayMaxLength	15	A `GNArray` member contains more items than allowed.