Overview
Perform the GetPlayersWithTag operation.
Client
Require permission rules characterPlayer.getPlayersWithTag.selfEnable. See PermissionRules
HTTP
POST /api/rJson/characterPlayer/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 used in this request. (2 - 32 characters) |
| value | string | true | The specific value of the segment to be assigned to the character. (2 - 32 characters) |
| infoRequestParam | InfoRequestParam | true | Instructions on which additional profile fields to return in the response. See InfoRequestParam |
| skip | number int | Number of leaderboard entries to skip (used for pagination). (from 0) (Default: 0) | |
| limit | number int | Maximum number of leaderboard entries to return in the result set. (from 1 to 100) (Default: 10) |
Server
Require permission rules characterPlayer.getPlayersWithTag.serverSelfEnable. See PermissionRules
HTTP
POST /api/rJson/characterPlayer/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 used in this request. (2 - 32 characters) |
| value | string | true | The specific value of the segment to be assigned to the character. (2 - 32 characters) |
| infoRequestParam | InfoRequestParam | true | Instructions on which additional profile fields to return in the response. See InfoRequestParam |
| skip | number int | Number of leaderboard entries to skip (used for pagination). (from 0) (Default: 0) | |
| limit | number int | Maximum number of leaderboard entries to return in the result set. (from 1 to 100) (Default: 10) |
Admin
Require permission rules characterPlayer.getPlayersWithTag.adminSelfEnable. See PermissionRules
HTTP
POST /api/rJson/characterPlayer/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 used in this request. (2 - 32 characters) |
| value | string | true | The specific value of the segment to be assigned to the character. (2 - 32 characters) |
| infoRequestParam | InfoRequestParam | true | Instructions on which additional profile fields to return in the response. See InfoRequestParam |
| skip | number int | Number of leaderboard entries to skip (used for pagination). (from 0) (Default: 0) | |
| limit | number int | Maximum number of leaderboard entries to return in the result set. (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 | CharacterPlayerWithCharacterIdResponseData[] | true | Results field used in the CharacterPlayersWithCharacterIdResponseData model. See CharacterPlayerWithCharacterIdResponseData |
InfoRequestParam
Data model for InfoRequestParam.
| Code | Type | Required | Description |
|---|---|---|---|
| catalogId | boolean | CatalogId field used in the InfoRequestParam model. (Default: false) | |
| owner | boolean | Owner field used in the InfoRequestParam model. (Default: false) | |
| removeStatus | boolean | RemoveStatus field used in the InfoRequestParam model. (Default: false) | |
| segments | boolean | Segments field used in the InfoRequestParam model. (Default: false) | |
| customDatas | boolean | CustomDatas field used in the InfoRequestParam model. (Default: false) | |
| displayName | boolean | DisplayName field used in the InfoRequestParam model. (Default: false) | |
| avatar | boolean | Avatar field used in the InfoRequestParam model. (Default: false) | |
| tsCreate | boolean | TsCreate field used in the InfoRequestParam model. (Default: false) | |
| tags | boolean | Tags field used in the InfoRequestParam model. (Default: false) | |
| playerBan | boolean | PlayerBan field used in the InfoRequestParam model. (Default: false) | |
| playerCurrencies | boolean | PlayerCurrencies field used in the InfoRequestParam model. (Default: false) | |
| playerStatistics | boolean | PlayerStatistics field used in the InfoRequestParam model. (Default: false) | |
| playerDatas | boolean | PlayerDatas field used in the InfoRequestParam model. (Default: false) | |
| ipAddressCreate | boolean | IpAddressCreate field used in the InfoRequestParam model. (Default: false) | |
| countryCode | boolean | CountryCode field used in the InfoRequestParam model. (Default: false) | |
| tsLastLogin | boolean | TsLastLogin field used in the InfoRequestParam model. (Default: false) | |
| playerInventories | boolean | PlayerInventories field used in the InfoRequestParam model. (Default: false) | |
| playerGroups | boolean | PlayerGroups field used in the InfoRequestParam model. (Default: false) | |
| playerFriends | boolean | PlayerFriends field used in the InfoRequestParam model. (Default: false) | |
| playerDataKeys | string[] | PlayerDataKeys field used in the InfoRequestParam model. | |
| playerCurrencyKeys | string[] | PlayerCurrencyKeys field used in the InfoRequestParam model. | |
| playerStatisticsKeys | string[] | PlayerStatisticsKeys field used in the InfoRequestParam model. | |
| customDataKeys | string[] | CustomDataKeys field used in the InfoRequestParam model. | |
| tagKeys | string[] | TagKeys field used in the InfoRequestParam model. | |
| characterCatalogIds | string[] | CharacterCatalogIds field used in the InfoRequestParam model. | |
| itemCatalogIds | string[] | ItemCatalogIds field used in the InfoRequestParam model. | |
| groupCatalogIds | string[] | GroupCatalogIds field used in the InfoRequestParam model. | |
| friendCatalogIds | string[] | FriendCatalogIds field used in the InfoRequestParam model. |
CharacterPlayerWithCharacterIdResponseData
Data model for CharacterPlayerWithCharacterIdResponseData.
| Code | Type | Required | Description |
|---|---|---|---|
| characterId | string | true | CharacterId field used in the CharacterPlayerWithCharacterIdResponseData model. |
| infoResponseParameters | InfoResponseParameters | true | InfoResponseParameters field used in the CharacterPlayerWithCharacterIdResponseData model. See InfoResponseParameters |
InfoResponseParameters
Data model for InfoResponseParameters.
| Code | Type | Required | Description |
|---|---|---|---|
| catalogId | string | CatalogId field used in the InfoResponseParameters model. | |
| owner | GenericModels.OwnerItem | Owner field used in the InfoResponseParameters model. See GenericModels.OwnerItem | |
| removeStatus | GenericModels.RemoveStatusItem | RemoveStatus field used in the InfoResponseParameters model. See GenericModels.RemoveStatusItem | |
| segments | string[] | Segments field used in the InfoResponseParameters model. | |
| customDatas | GenericModels.DataItem[] | CustomDatas field used in the InfoResponseParameters model. See GenericModels.DataItem | |
| displayName | string | DisplayName field used in the InfoResponseParameters model. | |
| avatar | GenericModels.AvatarItem | Avatar field used in the InfoResponseParameters model. See GenericModels.AvatarItem | |
| tsCreate | number | TsCreate field used in the InfoResponseParameters model. | |
| tags | GenericModels.TagItem[] | Tags field used in the InfoResponseParameters model. See GenericModels.TagItem | |
| playerBan | GenericModels.BanItem | PlayerBan field used in the InfoResponseParameters model. See GenericModels.BanItem | |
| playerDatas | GenericModels.DataItem[] | PlayerDatas field used in the InfoResponseParameters model. See GenericModels.DataItem | |
| playerCurrencies | GenericModels.CurrencyItem[] | PlayerCurrencies field used in the InfoResponseParameters model. See GenericModels.CurrencyItem | |
| playerStatistics | GenericModels.StatisticsItem[] | PlayerStatistics field used in the InfoResponseParameters model. See GenericModels.StatisticsItem | |
| playerInventories | GenericModels.InventoryItem[] | PlayerInventories field used in the InfoResponseParameters model. See GenericModels.InventoryItem | |
| playerGroups | GenericModels.GroupItem[] | PlayerGroups field used in the InfoResponseParameters model. See GenericModels.GroupItem | |
| playerFriends | GenericModels.FriendItem[] | PlayerFriends field used in the InfoResponseParameters model. See GenericModels.FriendItem | |
| tsLastLogin | number | TsLastLogin field used in the InfoResponseParameters model. | |
| ipAddressCreate | string | IpAddressCreate field used in the InfoResponseParameters model. | |
| countryCode | string | CountryCode field used in the InfoResponseParameters model. |
Generic.OwnerItem
Represents the current owner of an entity such as an inventory item, character or group...
| Code | Type | Required | Description |
|---|---|---|---|
| type | number | true | Owner type. Map this value with the public `OwnerType` enum. |
| id | string | true | Owner id paired with `type`. |
Generic.RemoveStatusItem
Represents soft-remove metadata for an entity.
| Code | Type | Required | Description |
|---|---|---|---|
| tsRemove | number | true | Removal timestamp when the entity was soft-removed. |
| reason | string | Removal reason when the backend provides one. |
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.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. |
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. |