> ## Documentation Index > Fetch the complete documentation index at: https://cometchat-22654f5b-docs-ios-ui-kit-sdk-fixes.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve Users > Guide to fetching user details and lists using the CometChat iOS SDK UsersRequest builder with search and filtering. **Quick Reference for AI Agents & Developers** * **Get logged-in user:** `CometChat.getLoggedInUser()` * **Get specific user:** `CometChat.getUser(UID:onSuccess:onError:)` * **Build request:** `UsersRequest.UsersRequestBuilder().set(limit:).build()` * **Fetch users:** `usersRequest.fetchNext(onSuccess:onError:)` * **Filters:** `.set(searchKeyword:)`, `.set(status:)`, `.set(roles:)`, `.set(tags:)` * **Related:** [User Management](/sdk/ios/user-management) · [Block Users](/sdk/ios/block-users) · [Users Overview](/sdk/ios/users-overview) ## Retrieve Logged In User Details You can get the details of the logged-in user using the `getLoggedInUser()` method. This method can also be used to check if the user is logged in or not. If the method returns `nil`, it indicates that the user is not logged in and you need to log the user into CometChat SDK. ```swift theme={null} let user = CometChat.getLoggedInUser(); ``` ```objc theme={null} User *user = [CometChat getLoggedInUser]; ``` This method will return a `User` object containing all the information related to the logged-in user. **Success Response ([User](#user-object) Object):** | Parameter | Type | Description | | ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | uid | String? | Unique identifier of the user. Example: `"cometchat-uid-2"` | | name | String? | Display name of the user. Example: `"George Alan"` | | avatar | String? | URL to the user's avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"` | | link | String? | URL to the user's profile page. Example: `nil` | | role | String? | Role assigned to the user for access control. Example: `"moderator"` | | status | [UserStatus](#userstatus-enum) | Current online status of the user. Example: `.online` | | statusMessage | String? | Custom status message set by the user. Example: `nil` | | lastActiveAt | Double | Unix timestamp of the user's last activity. Example: `1772088145.0` | | hasBlockedMe | Bool | Indicates if this user has blocked the logged-in user. Example: `false` | | blockedByMe | Bool | Indicates if the logged-in user has blocked this user. Example: `false` | | deactivatedAt | Double | Unix timestamp when user was deactivated (0 if active). Example: `0.0` | | tags | \[String] | Array of tags associated with the user. Example: `[]` | | metadata | \[String: Any]? | Custom metadata dictionary for additional user info. Example: `[:]` | Returns `nil` if no user is logged in. Use this to check login state. ## Retrieve List of Users In order to fetch the list of users, you can use the `UsersRequest` class. To use this class i.e to create an object of the UsersRequest class, you need to use the `UsersRequestBuilder` class. The `UsersRequestBuilder` class allows you to set the parameters based on which the users are to be fetched. ### UsersRequestBuilder Methods | Method | Type | Description | | ---------------------- | ------------------------------ | -------------------------------------------- | | `set(limit:)` | Int | Number of users to fetch per request (1-100) | | `set(searchKeyword:)` | String | Search string to filter users | | `searchIn(_:)` | \[String] | Properties to search in: "uid", "name" | | `set(status:)` | [UserStatus](#userstatus-enum) | Filter by `.online` or `.offline` | | `hideBlockedUsers(_:)` | Bool | Exclude blocked users from results | | `set(roles:)` | \[String] | Filter by user roles | | `friendsOnly(_:)` | Bool | Return only friends | | `set(tags:)` | \[String] | Filter by user tags | | `withTags(_:)` | Bool | Include tags in response | | `setUIDs(_:)` | \[String] | Fetch specific users by UID (max 25) | | `sortBy(_:)` | String | Sort by property: "name", "status" | | `sortOrder(_:)` | SortOrder | `.asc` or `.desc` | **Builder Configuration:** | Parameter | Type | Description | | ---------------- | ------------------------------ | ------------------------------------------------------------------------- | | limit | Int | Maximum number of users to fetch per request. Range: 1-100. Example: `30` | | searchKeyword | String | Search string to filter users by UID or name. Example: `"john"` | | searchIn | \[String] | Properties to search in. Example: `["uid", "name"]` | | status | [UserStatus](#userstatus-enum) | Filter by online status. Example: `.online` or `.offline` | | hideBlockedUsers | Bool | Whether to exclude blocked users from results. Example: `true` | | roles | \[String] | Filter users by their assigned roles. Example: `["admin", "moderator"]` | | friendsOnly | Bool | Return only users who are friends. Example: `true` | | tags | \[String] | Filter users by tags. Example: `["premium", "verified"]` | | withTags | Bool | Include tags data in response. Example: `true` | | UIDs | \[String] | Fetch specific users by UID (max 25). Example: `["user1", "user2"]` | | sortBy | String | Property to sort by. Example: `"name"` | | sortOrder | SortOrder | Sort direction. Example: `.asc` or `.desc` | **Search In Values:** | Value | Description | | ---------------- | ------------------------------------- | | "uid" | Search in user UID field | | "name" | Search in user display name field | | \["uid", "name"] | Search in both UID and name (default) | **Sort Order:** | Sort Pattern | Description | | --------------------- | ---------------------------------------------- | | status => name => UID | Default sorting order when no sortBy specified | | name => UID | Sorting order when sortBy is "name" | **Common Filter Combinations:** | Use Case | Builder Configuration | | -------------------------- | ---------------------------------------------------- | | Fetch online users only | `.set(status: .online).set(limit: 30)` | | Search users by name | `.set(searchKeyword: "john").searchIn(["name"])` | | Fetch friends only, sorted | `.friendsOnly(true).sortBy("name").sortOrder(.asc)` | | Fetch users with tags | `.set(tags: ["premium", "verified"]).withTags(true)` | | Fetch specific users | `.setUIDs(["user1", "user2", "user3"])` | ### Set Limit This method sets the limit i.e. the number of users that should be fetched in a single iteration. ```swift theme={null} let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .build() ``` ### Set Search Keyword This method allows you to set the search string based on which the users are to be fetched. ```swift theme={null} let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .set(searchKeyword: "abc") .build() ``` ### Search In This method allows you to define in which user property should the searchKeyword be searched. This method only works in combination with `setSearchKeyword()`. By default the keyword is searched in both UID & Name. ```swift theme={null} let searchKeyword = "super" let searchIn = ["uid", "name"] let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .set(searchKeyword: searchKeyword) .searchIn(searchIn) .build() ``` **Search In Values:** | Value | Description | | ---------------- | ------------------------ | | "uid" | Search in user UID | | "name" | Search in user name | | \["uid", "name"] | Search in both (default) | ### Set Status The status based on which the users are to be fetched. The status parameter can contain one of the below two values: * CometChat.UserStatus.online - will return the list of only online users. * CometChat.UserStatus.offline - will return the list of only offline users. If this parameter is not set, will return all the available users. ```swift theme={null} let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .set(status: .online) .build() ``` ### Hide Blocked Users This method is used to determine if the blocked users should be returned as a part of the user list. if set to true, the user list will not contain the users blocked by the logged-in user. ```swift theme={null} let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .hideBlockedUsers(true) .build() ``` ### Set Roles This method allows you to fetch the users based on multiple roles. ```swift theme={null} let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .set(roles : ["role1","role2"]) .build() ``` ### Friends Only This property when set to true will return only the friends of the logged-in user. ```swift theme={null} let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .friendsOnly(true) .build(); ``` ### Set Tags This method accepts a list of tags based on which the list of users is to be fetched. The list fetched will only contain the users that have been tagged with the specified tags. ```swift theme={null} let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .set(tags: ["tag1", "tag2"]) .build(); ``` ### With Tags This property when set to true will fetch tags data along with the list of users. ```swift theme={null} let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: 30) .withTags(true) .build() ``` ### Set UIDs This method accepts a list of UIDs based on which the list of users is fetched. A maximum of 25 users can be fetched. ```swift theme={null} let UIDs = ["cometchat-uid-1", "cometchat-uid-2"] let limit = 30 let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: limit) .setUIDs(UIDs) .build(); ``` ### Sort By This method allows you to sort the User List by a specific property of User. By default the User List is sorted by `status => name => UID` . If `name` is pass to the `sortBy()` method the user list will be sorted by `name => UID`. ```swift theme={null} let sortBy = "name" let limit = 30 let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: limit) .sortBy(sortBy) .build(); ``` **Sort Order:** | Default Sort | Description | | --------------------- | --------------------- | | status => name => UID | Default sorting order | | name => UID | When sortBy is "name" | ### Sort By Order This method allows you to sort the User List in a specific order. By default the user list is sorted in ascending order. ```swift theme={null} let limit = 30 let usersRequest = UsersRequest.UsersRequestBuilder() .set(limit: limit) .sortOrder(.desc) .build(); ``` Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the UsersRequest class. Once you have the object of the `UsersRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of `User` objects containing n number of users where n is the limit set in the builder class. ```swift theme={null} let limit = 20; let usersRequest = UsersRequest.UsersRequestBuilder(limit: limit).build(); usersRequest.fetchNext(onSuccess: { (users) in for user in users { print("User: " + user.stringValue()) } }) { (error) in print("User list fetching failed with error: " + error!.errorDescription); } ``` ```objc theme={null} NSInteger limit = 30 ; UsersRequest *userRequest = [[[UsersRequestBuilder alloc]initWithLimit:limit] build]; [userRequest fetchNextOnSuccess:^(NSArray * users) { for (User *user in users) { NSLog(@"User: %@ ",[user stringValue]); } } onError:^(CometChatException * error) { NSLog(@"User list fetching failed with error: %@",[error errorDescription]); }]; ``` **Request Parameters:** | Parameter | Type | Description | | --------- | ---- | --------------------------------------------------------------- | | limit | Int | Maximum number of users to fetch in this request. Example: `30` | **Success Response (Array of [User](#user-object) Objects):** | Parameter | Type | Description | | ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | uid | String? | Unique identifier of the user. Example: `"cometchat-uid-1"` | | name | String? | Display name of the user. Example: `"Andrew Joseph"` | | avatar | String? | URL to the user's avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` | | link | String? | URL to the user's profile page. Example: `nil` | | role | String? | Role assigned to the user for access control. Example: `"admin"` | | status | [UserStatus](#userstatus-enum) | Current online status of the user. Example: `.offline` | | statusMessage | String? | Custom status message set by the user. Example: `nil` | | lastActiveAt | Double | Unix timestamp of the user's last activity. Example: `1772017498.0` | | hasBlockedMe | Bool | Indicates if this user has blocked the logged-in user. Example: `false` | | blockedByMe | Bool | Indicates if the logged-in user has blocked this user. Example: `false` | | deactivatedAt | Double | Unix timestamp when user was deactivated (0 if active). Example: `0.0` | | tags | \[String] | Array of tags associated with the user. Example: `[]` | | metadata | \[String: Any]? | Custom metadata dictionary for additional user info. Example: `[:]` | **Error Response ([CometChatException](#common-error-codes)):** | Parameter | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------------------- | | errorCode | String | Unique error code identifying the error type. Example: `"ERR_INVALID_LIMIT"` | | errorDescription | String | Human-readable description of the error. Example: `"Invalid limit value provided"` | ## Retrieve Particular User Details To get the information of a user, you can use the `getUser()` method. ```swift theme={null} let uid = "cometchat-uid-1"; CometChat.getUser(UID: uid, onSuccess: { (user) in print("User: " + user.stringValue()) }) { (error) in print("User fetching failed with error: " + error.errorDescription); } ``` ```objc theme={null} NSString *UID = @"cometchat-uid-1"; [CometChat getUserWithUID:UID onSuccess:^(User * user) { NSLog(@"User: %@",[user stringValue]); } onError:^(CometChatException * error) { NSLog(@"User fetching failed with error: %@",[error errorDescription]); }]; ``` The `getUser()` method takes the following parameters: | Parameter | Description | | --------- | ------------------------------------------------------------- | | UID | The `UID` of the user for whom the details are to be fetched. | **Request Parameters:** | Parameter | Type | Description | | --------- | ------ | -------------------------------------------------------------------- | | UID | String | Unique identifier of the user to fetch. Example: `"cometchat-uid-2"` | **Success Response ([User](#user-object) Object):** | Parameter | Type | Description | | ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | uid | String? | Unique identifier of the user. Example: `"cometchat-uid-2"` | | name | String? | Display name of the user. Example: `"George Alan"` | | avatar | String? | URL to the user's avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"` | | link | String? | URL to the user's profile page. Example: `nil` | | role | String? | Role assigned to the user for access control. Example: `"moderator"` | | status | [UserStatus](#userstatus-enum) | Current online status of the user. Example: `.online` | | statusMessage | String? | Custom status message set by the user. Example: `nil` | | lastActiveAt | Double | Unix timestamp of the user's last activity. Example: `1772104307.0` | | hasBlockedMe | Bool | Indicates if this user has blocked the logged-in user. Example: `false` | | blockedByMe | Bool | Indicates if the logged-in user has blocked this user. Example: `false` | | deactivatedAt | Double | Unix timestamp when user was deactivated (0 if active). Example: `0.0` | | tags | \[String] | Array of tags associated with the user. Example: `[]` | | metadata | \[String: Any]? | Custom metadata dictionary for additional user info. Example: `[:]` | **Error Response ([CometChatException](#common-error-codes)):** | Parameter | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------ | | errorCode | String | Unique error code identifying the error type. Example: `"ERR_UID_NOT_FOUND"` | | errorDescription | String | Human-readable description of the error. Example: `"User with the specified UID does not exist"` | *** ## User Object The `User` object represents a CometChat user with all their profile information. See [Users Overview](/sdk/ios/users-overview) for complete details. | Parameter | Type | Description | | ------------- | ------------------------------ | --------------------------------------------------------------------- | | uid | String? | Unique identifier of the user (required, not editable after creation) | | name | String? | Display name of the user (required) | | avatar | String? | URL to the user's avatar image | | link | String? | URL to the user's profile page | | role | String? | Role assigned to the user for access control | | status | [UserStatus](#userstatus-enum) | Current online status: `.online` or `.offline` | | statusMessage | String? | Custom status message set by the user | | lastActiveAt | Double | Unix timestamp of the user's last activity | | hasBlockedMe | Bool | Indicates if this user has blocked the logged-in user | | blockedByMe | Bool | Indicates if the logged-in user has blocked this user | | deactivatedAt | Double | Unix timestamp when user was deactivated (0 if active) | | tags | \[String] | Array of tags associated with the user | | metadata | \[String: Any]? | Custom metadata dictionary for additional user info | ## UserStatus Enum | Value | Raw Value | Description | | -------- | --------- | ----------------------------------- | | .online | 0 | User is currently online and active | | .offline | 1 | User is currently offline | ## Common Error Codes | Error Code | Description | Resolution | | -------------------- | -------------------------------------- | ------------------------------------- | | ERR\_NOT\_LOGGED\_IN | User is not logged in | Login first using `CometChat.login()` | | ERR\_UID\_NOT\_FOUND | User with specified UID does not exist | Verify the UID is correct | | ERR\_INVALID\_LIMIT | Invalid limit value provided | Use a limit between 1-100 |