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

# Retrieve Group Members

> Fetch and filter group members by scope, status, and search keyword using the CometChat Flutter SDK with pagination support.

<Accordion title="AI Integration Quick Reference">
  ```dart theme={null}
  // Retrieve group members with pagination
  GroupMembersRequest request = (GroupMembersRequestBuilder("GROUP_ID")
    ..limit = 30
  ).build();

  await request.fetchNext(
    onSuccess: (List<GroupMember> members) {
      for (GroupMember member in members) {
        debugPrint("Member: ${member.name}, Scope: ${member.scope}");
      }
    },
    onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
  );

  // Filter by scope (admin, moderator, participant)
  GroupMembersRequest scopedRequest = (GroupMembersRequestBuilder("GROUP_ID")
    ..limit = 30
    ..scopes = ["admin", "moderator"]
  ).build();

  // Search members
  GroupMembersRequest searchRequest = (GroupMembersRequestBuilder("GROUP_ID")
    ..limit = 30
    ..searchKeyword = "john"
  ).build();
  ```
</Accordion>

Fetch the members of a group with filtering by scope, online status, and search keyword. Results are returned as [`GroupMember`](/sdk/reference/entities#groupmember) objects, which extend [`User`](/sdk/reference/entities#user) with group-specific fields like scope.

## Retrieve the List of Group Members

In order to fetch the list of groups members for a group, you can use the `GroupMembersRequest` class.

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

To use this class i.e to create an object of the `GroupMembersRequest` class, you need to use the `GroupMembersRequestBuilder` class. The `GroupMembersRequestBuilder` class allows you to set the parameters based on which the groups are to be fetched.

The `GUID` of the group for which the members are to be fetched must be specified in the constructor of the `GroupMembersRequestBuilder` class.

### GroupMembersRequestBuilder

| Parameter       | Type            | Description                                                                                 |
| --------------- | --------------- | ------------------------------------------------------------------------------------------- |
| `guid`          | `String`        | **(Required, constructor)** Group ID for the group whose members are to be fetched.         |
| `limit`         | `int?`          | Maximum number of members to fetch per request. Max `100`, default `30`.                    |
| `searchKeyword` | `String?`       | Search string to filter members by name.                                                    |
| `scopes`        | `List<String>?` | Filter members by scope (`"admin"`, `"moderator"`, `"participant"`).                        |
| `status`        | `String?`       | Filter members by online status (`"online"`, `"offline"`). If not set, returns all members. |
| `setPage`       | `int?`          | Fetch group members from a particular page number.                                          |

### Set Limit

This method sets the limit i.e. the number of members that should be fetched in a single iteration.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String GUID = "GUID";
      GroupMembersRequest  groupMembersRequest = (GroupMembersRequestBuilder(GUID)
      ..limit = 20
      ).build();
    ```
  </Tab>
</Tabs>

### Set Search Keyword

This method allows you to set the search string based on which the group members are to be fetched.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String GUID = "GUID";
    GroupMembersRequest  groupMembersRequest = (GroupMembersRequestBuilder(GUID)
      ..limit = 20
      ..searchKeyword = "abc"
      ).build();
    ```
  </Tab>
</Tabs>

### Set Scopes

This method allows you to fetch group members based on the specified scopes.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> scopes =[];
    scopes.add("admin");
    scopes.add("moderator");
    String GUID = "GUID";
    GroupMembersRequest  groupMembersRequest = (GroupMembersRequestBuilder(GUID)
      ..limit = 20
      ..scopes = scopes
      ).build();
    ```
  </Tab>
</Tabs>

Relevant fields to access on returned members:

| Field | Property | Return Type | Description                                                                     |
| ----- | -------- | ----------- | ------------------------------------------------------------------------------- |
| scope | `scope`  | `String`    | Scope of the member in the group (`"admin"`, `"moderator"`, or `"participant"`) |

### Set Status

Filters members by online status:

| Value       | Description          |
| ----------- | -------------------- |
| `"online"`  | Only online members  |
| `"offline"` | Only offline members |

If not set, returns all members regardless of status.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String GUID = "GUID";
    GroupMembersRequest groupMembersRequest = (GroupMembersRequestBuilder(GUID)
      ..limit = 20
      ..status = "online"
    ).build();
    ```
  </Tab>
</Tabs>

Finally, once all the parameters are set to the builder class, you need to call the `build()` method to get the object of the `GroupMembersRequest` class.

Once you have the object of the `GroupMembersRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of `GroupMember` objects containing N number of members depending on the limit set.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String GUID = "GUID";
    GroupMembersRequest  groupMembersRequest = (GroupMembersRequestBuilder(GUID)
      ..limit = 20
      ).build();

    groupMembersRequest.fetchNext(onSuccess: (List<GroupMember> groupMemberList){
        debugPrint("Group Members fetched Successfully : $groupMemberList ");  
      }, onError: (CometChatException e) {
        debugPrint("Delete Group failed with exception: ${e.message}");
      });
    ```
  </Tab>
</Tabs>

The `fetchNext()` method returns a list of [`GroupMember`](/sdk/reference/entities#groupmember) objects. `GroupMember` extends [`User`](/sdk/reference/entities#user) and adds group-specific fields.

<Accordion title="Response">
  **On Success** — A `List<GroupMember>` containing the group members for the specified group (each item is a `GroupMember` object):

  <span id="retrieve-group-members-groupmember-object" style={{scrollMarginTop: '100px'}} />

  **GroupMember Object (per item in array):**

  | 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`                                                            |
  | `scope`         | string  | Member scope in the group                        | `"admin"`                                                               |
  | `joinedAt`      | number  | Epoch timestamp when the member joined the group | `1745550000`                                                            |
</Accordion>

<Accordion title="Error">
  | Parameter | Type   | Description                  | Sample Value                                  |
  | --------- | ------ | ---------------------------- | --------------------------------------------- |
  | `code`    | string | Error code identifier        | `"ERR_GUID_NOT_FOUND"`                        |
  | `message` | string | Human-readable error message | `"The specified group does not exist."`       |
  | `details` | string | Additional technical details | `"Please verify the group ID and try again."` |
</Accordion>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Add Members" icon="user-plus" href="/sdk/flutter/group-add-members">
    Add new members to your groups
  </Card>

  <Card title="Kick/Ban Members" icon="user-slash" href="/sdk/flutter/group-kick-ban-members">
    Remove or ban members from groups
  </Card>
</CardGroup>