> ## 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 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/v4/group-kick-ban-members">
    Remove or ban members from groups
  </Card>
</CardGroup>


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