Retrieve Users

Fetch, filter, search, and sort users using the CometChat Flutter SDK. Includes pagination, role-based filtering, tag support, and online user counts.

AI Integration Quick Reference

// Fetch users list
UsersRequest usersRequest = (UsersRequestBuilder()..limit = 30).build();
usersRequest.fetchNext(
  onSuccess: (List<User> userList) => debugPrint("Users: $userList"),
  onError: (CometChatException e) => debugPrint("Error: ${e.message}")
);

// Get specific user details
CometChat.getUser("UID",
  onSuccess: (User user) => debugPrint("User: $user"),
  onError: (CometChatException e) => debugPrint("Error: ${e.message}")
);

// Get logged-in user
User? user = await CometChat.getLoggedInUser();

// Get online user count
CometChat.getOnlineUserCount(
  onSuccess: (int count) => debugPrint("Online: $count"),
  onError: (CometChatException e) => debugPrint("Error: ${e.message}")
);

The CometChat SDK provides methods to retrieve the logged-in user, fetch filtered user lists, look up individual users by UID, and get online user counts. All user methods return User objects.

Available via: SDK | REST API | UI Kits

User Object Fields

Field	Type	Description
uid	String	Unique user ID
name	String	Display name of the user
avatar	String?	URL of the user’s avatar image
status	String	Online status of the user ("online" or "offline")
lastActiveAt	int?	Epoch timestamp when the user was last active
role	String	Role assigned to the user
tags	List<String>	Tags associated with the user

Retrieve Logged In User Details

Use getLoggedInUser() to get the current user’s details. Returns null if no user is logged in.

Dart

User? user = await CometChat.getLoggedInUser();

This method returns a User object with the logged-in user’s information.

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.

Fetching using this builder will return User objects.

UsersRequestBuilder Parameters

Parameter	Type	Description
limit	int?	Number of users to fetch per request
searchKeyword	String?	Filters users by a search string
searchIn	List<String>?	Specifies which user properties to search ("uid", "name"). Works with searchKeyword.
userStatus	String?	Filters by online status (CometChatUserStatus.online or CometChatUserStatus.offline)
hideBlockedUsers	bool?	When true, excludes users blocked by the logged-in user
roles	List<String>?	Filters users by specified roles
friendsOnly	bool?	When true, returns only friends of the logged-in user
tags	List<String>?	Filters users by specified tags
withTags	bool?	When true, includes tag data in the returned user objects
uids	List<String>?	Fetches specific users by their UIDs. Maximum 25 per request.
sortBy	String?	Sorts the user list by a specific property. Default sort order: status → name → UID. Pass "name" to sort by name → UID.
sortByOrder	String?	Sets the sort order. Default is ascending ("asc"). Use "desc" for descending.

The UsersRequestBuilder class allows you to set the below parameters:

Set Limit

Sets the number of users to fetch per request.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
  ).build();

Set Search Keyword

Filters users by a search string.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
	..searchKeyword = "abc"
  ).build();

Search In

Specifies which user properties to search. Works with searchKeyword. By default, searches both UID and name.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
  ..searchKeyword = "super"
  ..searchIn = ["uid", "name"]
  ).build();

Set Status

Filters users by online status:

• CometChatUserStatus.online — Only online users
• CometChatUserStatus.offline — Only offline users

If not set, returns all users.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
	..userStatus = CometChatUserStatus.online
  ).build(); 

Hide Blocked Users

When true, excludes users blocked by the logged-in user from the results.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
	..hideBlockedUsers = true
  ).build();  

Set Roles

Filters users by specified roles.

Dart

List<String> roles = [];
roles.add("role1");
roles.add("role2");
UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
	..roles = roles
  ).build();

Friends Only

When true, returns only friends of the logged-in user.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
	..friendsOnly = true
  ).build();

Set Tags

Filters users by specified tags.

Dart

List<String> tags = [];
tags.add("tag1");
tags.add("tag2");
UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
	..tags = tags
  ).build();  

With Tags

When true, includes tag data in the returned user objects.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 50
	..withTags = true
  ).build();

Set UIDs

Fetches specific users by their UIDs. Maximum 25 users per request.

Dart

List<String> uids = [];
uids.add("UID1");
uids.add("UID2");
UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 25
	..uids = uids
  ).build(); 

Sort By

Sorts the user list by a specific property. Default sort order: status → name → UID. Pass "name" to sort by name → UID.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 30
  ..sortBy = "name"
  ).build();

Sort By Order

Sets the sort order. Default is ascending ("asc"). Use "desc" for descending.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 30
  ..sortByOrder = "desc"
  ).build();

After configuring the builder, call build() to get the UsersRequest object, then call fetchNext() to retrieve users.

Dart

UsersRequest usersRequest = (UsersRequestBuilder()
  ..limit = 25
  ).build();

usersRequest.fetchNext(onSuccess: (List<User> userList){
    debugPrint("User List Fetched Successfully : $userList");
  },onError: (CometChatException e){
    debugPrint("User List Fetch Failed: ${e.message}");
  });

The fetchNext() method returns a list of User objects.

Response

On Success — A list of User objects matching the request filters. Each item in the list contains:

User Object:

Parameter	Type	Description	Sample Value
uid	string	Unique identifier of the user	"cometchat-uid-1"
name	string	Display name of the user	"Andrew Joseph"
link	string	Profile link	null
avatar	string	Avatar URL	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"
metadata	object	Custom metadata	{}
status	string	Online status	"online"
role	string	User role	"default"
statusMessage	string	Status message	null
tags	array	User tags	[]
hasBlockedMe	boolean	Whether this user has blocked the current user	false
blockedByMe	boolean	Whether the current user has blocked this user	false
lastActiveAt	number	Epoch timestamp of last activity	1745554700

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_CHAT_API_FAILURE"
message	string	Human-readable error message	"Failed to fetch the requested data."
details	string	Additional technical details	"An unexpected error occurred while processing the request."

Retrieve Particular User Details

Use getUser() to fetch a specific user’s details by UID.

Dart

String UID = "UID";
  
CometChat.getUser(UID, onSuccess: (User user){
    debugPrint("User Fetched Successfully : $user");
  }, onError: (CometChatException e){
    debugPrint("User Fetch Failed: ${e.message}");
  });

The getUser() method takes the following parameters:

Parameter	Description
UID	The UID of the user for whom the details are to be fetched

On success, the User object containing the details of the user is returned.

Response

On Success — A User object containing the details of the requested user:

User Object:

Parameter	Type	Description	Sample Value
uid	string	Unique identifier of the user	"cometchat-uid-1"
name	string	Display name of the user	"Andrew Joseph"
link	string	Profile link	null
avatar	string	Avatar URL	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"
metadata	object	Custom metadata	{}
status	string	Online status	"online"
role	string	User role	"default"
statusMessage	string	Status message	null
tags	array	User tags	[]
hasBlockedMe	boolean	Whether this user has blocked the current user	false
blockedByMe	boolean	Whether the current user has blocked this user	false
lastActiveAt	number	Epoch timestamp of last activity	1745554700

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_UID_NOT_FOUND"
message	string	Human-readable error message	"The specified UID does not exist."
details	string	Additional technical details	"Please verify the UID and try again."

Get Online User Count

Use getOnlineUserCount() to get the total number of online users in your app.

Dart

CometChat.getOnlineUserCount(onSuccess: (int count){
    debugPrint("Online User Count: $count"); 
  }, onError: (CometChatException e){
    debugPrint("User Count Fetch Failed: ${e.message}");
  });

getOnlineUserCount() resolves with an int representing the total count of currently online users in your app.

Response

On Success — An int value representing the total count of online users:

Parameter	Type	Description	Sample Value
count	number	Total number of online users	12

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_CHAT_API_FAILURE"
message	string	Human-readable error message	"Failed to fetch the requested data."
details	string	Additional technical details	"An unexpected error occurred while processing the request."

---

Next Steps

User Presence

Monitor and manage real-time user online/offline status

Block Users

Block and unblock users to control interactions

User Management

Create, update, and delete users programmatically

Users Overview

Explore all user-related features and capabilities