> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Users

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

<Accordion title="AI Integration Quick Reference">
  ```dart theme={null}
  // 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}")
  );
  ```
</Accordion>

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`](/sdk/reference/entities#user) objects.

<Note>
  **Available via:** SDK | [REST API](https://api-explorer.cometchat.com) | [UI Kits](/ui-kit/flutter/overview)
</Note>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    User? user = await CometChat.getLoggedInUser();
    ```
  </Tab>
</Tabs>

This method returns a [`User`](/sdk/reference/entities#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`](/sdk/reference/entities#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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
      ).build();
    ```
  </Tab>
</Tabs>

### Set Search Keyword

Filters users by a search string.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
    	..searchKeyword = "abc"
      ).build();
    ```
  </Tab>
</Tabs>

### Search In

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
      ..searchKeyword = "super"
      ..searchIn = ["uid", "name"]
      ).build();
    ```
  </Tab>
</Tabs>

### Set Status

Filters users by online status:

* `CometChatUserStatus.online` — Only online users
* `CometChatUserStatus.offline` — Only offline users

If not set, returns all users.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
    	..userStatus = CometChatUserStatus.online
      ).build(); 
    ```
  </Tab>
</Tabs>

### Hide Blocked Users

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
    	..hideBlockedUsers = true
      ).build();  
    ```
  </Tab>
</Tabs>

### Set Roles

Filters users by specified roles.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> roles = [];
    roles.add("role1");
    roles.add("role2");
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
    	..roles = roles
      ).build();
    ```
  </Tab>
</Tabs>

### Friends Only

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
    	..friendsOnly = true
      ).build();
    ```
  </Tab>
</Tabs>

### Set Tags

Filters users by specified tags.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> tags = [];
    tags.add("tag1");
    tags.add("tag2");
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
    	..tags = tags
      ).build();  
    ```
  </Tab>
</Tabs>

### With Tags

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 50
    	..withTags = true
      ).build();
    ```
  </Tab>
</Tabs>

### Set UIDs

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> uids = [];
    uids.add("UID1");
    uids.add("UID2");
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 25
    	..uids = uids
      ).build(); 
    ```
  </Tab>
</Tabs>

### Sort By

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 30
      ..sortBy = "name"
      ).build();
    ```
  </Tab>
</Tabs>

### Sort By Order

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    UsersRequest usersRequest = (UsersRequestBuilder()
      ..limit = 30
      ..sortByOrder = "desc"
      ).build();
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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}");
      });
    ```
  </Tab>
</Tabs>

The `fetchNext()` method returns a list of [`User`](/sdk/reference/entities#user) objects.

<Accordion title="Response">
  **On Success** — A list of `User` objects matching the request filters. Each item in the list contains:

  <span id="retrieve-users-user-object" style={{scrollMarginTop: '100px'}} />

  **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` |
</Accordion>

<Accordion title="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."` |
</Accordion>

## Retrieve Particular User Details

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "UID";
      
    CometChat.getUser(UID, onSuccess: (User user){
        debugPrint("User Fetched Successfully : $user");
      }, onError: (CometChatException e){
        debugPrint("User Fetch Failed: ${e.message}");
      });
    ```
  </Tab>
</Tabs>

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.

<Accordion title="Response">
  **On Success** — A `User` object containing the details of the requested user:

  <span id="get-user-user-object" style={{scrollMarginTop: '100px'}} />

  **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` |
</Accordion>

<Accordion title="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."` |
</Accordion>

## Get Online User Count

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChat.getOnlineUserCount(onSuccess: (int count){
        debugPrint("Online User Count: $count"); 
      }, onError: (CometChatException e){
        debugPrint("User Count Fetch Failed: ${e.message}");
      });
    ```
  </Tab>
</Tabs>

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

<Accordion title="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` |
</Accordion>

<Accordion title="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."` |
</Accordion>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="User Presence" icon="circle-dot" href="/sdk/flutter/user-presence">
    Monitor and manage real-time user online/offline status
  </Card>

  <Card title="Block Users" icon="ban" href="/sdk/flutter/block-users">
    Block and unblock users to control interactions
  </Card>

  <Card title="User Management" icon="user-gear" href="/sdk/flutter/user-management">
    Create, update, and delete users programmatically
  </Card>

  <Card title="Users Overview" icon="users" href="/sdk/flutter/users-overview">
    Explore all user-related features and capabilities
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.