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

# Retrieve Groups

> Fetch, filter, and search groups using the CometChat Flutter SDK. Includes pagination, tag-based filtering, joined-only groups, and online member counts.

<Accordion title="AI Integration Quick Reference">
  ```dart theme={null}
  // Retrieve groups with pagination
  GroupsRequest request = (GroupsRequestBuilder()
    ..limit = 30
    ..searchKeyword = "search_term"
  ).build();

  await request.fetchNext(
    onSuccess: (List<Group> groups) {
      for (Group group in groups) {
        debugPrint("Group: ${group.name}");
      }
    },
    onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
  );

  // Get a specific group by GUID
  await CometChat.getGroup(
    "GROUP_ID",
    onSuccess: (Group group) => debugPrint("Group: ${group.name}"),
    onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
  );

  // Fetch only joined groups
  GroupsRequest joinedRequest = (GroupsRequestBuilder()
    ..limit = 30
    ..joinedOnly = true
  ).build();

  // Get online member count
  CometChat.getOnlineGroupMemberCount(["GUID"],
    onSuccess: (Map<String, int> count) => debugPrint("Count: $count"),
    onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
  );
  ```
</Accordion>

Retrieve groups allows you to fetch the list of groups you've joined and groups that are available, as well as get details for a specific group.

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

## Retrieve List of Groups

*In other words, as a logged-in user, how do I retrieve the list of groups I've joined and groups that are available?*

In order to fetch the list of groups, you can use the `GroupsRequest` class. To use this class i.e to create an object of the `GroupsRequest` class, you need to use the `GroupsRequestBuilder` class. The `GroupsRequestBuilder` class allows you to set the parameters based on which the groups are to be fetched.

Use `GroupsRequestBuilder` to fetch groups with filtering, searching, and pagination.

### GroupsRequestBuilder

| Parameter       | Type            | Description                                                                         |
| --------------- | --------------- | ----------------------------------------------------------------------------------- |
| `limit`         | `int?`          | Maximum number of groups to fetch per request. Max `100`, default `30`.             |
| `searchKeyword` | `String?`       | Search string to filter groups by name.                                             |
| `joinedOnly`    | `bool?`         | When `true`, returns only groups the logged-in user has joined. Default `false`.    |
| `tags`          | `List<String>?` | List of tags to filter groups by. Only groups with the specified tags are returned. |
| `withTags`      | `bool?`         | When `true`, includes tag data in the returned group objects. Default `false`.      |
| `setPage`       | `int?`          | Fetch groups from a particular page number.                                         |

### Set Limit

Sets the number of groups to fetch per request.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    GroupsRequest groupsRequest =  (GroupsRequestBuilder()
      ..limit= 20
    ).build();
    ```
  </Tab>
</Tabs>

### Set Search Keyword

Filters groups by a search string.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    GroupsRequest groupsRequest =  (GroupsRequestBuilder()
      ..limit= 20
      ..searchKeyword = "abc"  
    ).build();  
    ```
  </Tab>
</Tabs>

### Joined Only

When `true`, returns only groups the logged-in user has joined or is a part of.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    GroupsRequest groupsRequest =  (GroupsRequestBuilder()
      ..limit= 20
      ..joinedOnly = true
    ).build();
    ```
  </Tab>
</Tabs>

### Set Tags

Filters groups by specified tags. The list fetched will only contain the groups that have been tagged with the specified tags.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> tags =[];
    tags.add("archived");
    GroupsRequest groupsRequest =  (GroupsRequestBuilder()
      ..limit= 20
       ..tags = tags
    ).build();
    ```
  </Tab>
</Tabs>

### With Tags

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    GroupsRequest groupsRequest =  (GroupsRequestBuilder()
      ..limit= 20
      ..withTags = true
    ).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 `GroupsRequest` class.

Once you have the object of the `GroupsRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of [`Group`](/sdk/reference/entities#group) objects containing 'n' number of groups depending on the limit set.

The list of groups fetched will only have the public and password type groups. The private groups will only be available if the user is a member of that private group.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    GroupsRequest groupsRequest =  (GroupsRequestBuilder()
      ..limit= 20
    ).build();

    groupsRequest.fetchNext(onSuccess: (List<Group> groupList) {
        debugPrint("Fetched Group Successfully : $groupList ");
      }, onError: (CometChatException e) {
        debugPrint("Group Request failed with exception: ${e.message}");
      });
    ```
  </Tab>
</Tabs>

<Accordion title="Response">
  **On Success** — A `List<Group>` containing the fetched groups. Each `Group` object has the following structure:

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

  **Group Object:**

  | Parameter           | Type    | Description                                              | Sample Value                |
  | ------------------- | ------- | -------------------------------------------------------- | --------------------------- |
  | `guid`              | string  | Unique identifier for the group                          | `"cometchat-guid-1"`        |
  | `name`              | string  | Display name of the group                                | `"Tech Enthusiasts"`        |
  | `icon`              | string  | URL of the group icon                                    | `null`                      |
  | `description`       | string  | Description of the group                                 | `"A group for tech lovers"` |
  | `membersCount`      | number  | Number of members in the group                           | `12`                        |
  | `metadata`          | object  | Custom metadata attached to the group                    | `{}`                        |
  | `joinedAt`          | number  | Epoch timestamp when the logged-in user joined the group | `1745554729`                |
  | `hasJoined`         | boolean | Whether the logged-in user has joined the group          | `true`                      |
  | `createdAt`         | number  | Epoch timestamp when the group was created               | `1745554729`                |
  | `owner`             | string  | UID of the group owner                                   | `"cometchat-uid-1"`         |
  | `updatedAt`         | number  | Epoch timestamp when the group was last updated          | `1745554729`                |
  | `tags`              | array   | List of tags associated with the group                   | `[]`                        |
  | `type`              | string  | Type of the group (public, private, password)            | `"public"`                  |
  | `scope`             | string  | Scope of the logged-in user in the group                 | `"admin"`                   |
  | `password`          | string  | Password for password-protected groups                   | `null`                      |
  | `isBannedFromGroup` | boolean | Whether the logged-in user is banned from the group      | `false`                     |
</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 Group Details

*In other words, as a logged-in user, how do I retrieve information for a specific group?*

To get the information of a group, you can use the `getGroup()` method.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String GUID = "GUID";

    CometChat.getGroup(GUID, onSuccess: (Group group) {
          debugPrint("Fetched Group Successfully : $group ");
        }, onError: (CometChatException e) {
          debugPrint("Group Request failed with exception: ${e.message}");
        });
    ```
  </Tab>
</Tabs>

| Parameter | Description                                                  |
| --------- | ------------------------------------------------------------ |
| `GUID`    | The GUID of the group for whom the details are to be fetched |

On success, the [`Group`](/sdk/reference/entities#group) object containing the details of the group is returned.

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

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

  **Group Object:**

  | Parameter           | Type    | Description                                              | Sample Value                |
  | ------------------- | ------- | -------------------------------------------------------- | --------------------------- |
  | `guid`              | string  | Unique identifier for the group                          | `"cometchat-guid-1"`        |
  | `name`              | string  | Display name of the group                                | `"Tech Enthusiasts"`        |
  | `icon`              | string  | URL of the group icon                                    | `null`                      |
  | `description`       | string  | Description of the group                                 | `"A group for tech lovers"` |
  | `membersCount`      | number  | Number of members in the group                           | `12`                        |
  | `metadata`          | object  | Custom metadata attached to the group                    | `{}`                        |
  | `joinedAt`          | number  | Epoch timestamp when the logged-in user joined the group | `1745554729`                |
  | `hasJoined`         | boolean | Whether the logged-in user has joined the group          | `true`                      |
  | `createdAt`         | number  | Epoch timestamp when the group was created               | `1745554729`                |
  | `owner`             | string  | UID of the group owner                                   | `"cometchat-uid-1"`         |
  | `updatedAt`         | number  | Epoch timestamp when the group was last updated          | `1745554729`                |
  | `tags`              | array   | List of tags associated with the group                   | `[]`                        |
  | `type`              | string  | Type of the group (public, private, password)            | `"public"`                  |
  | `scope`             | string  | Scope of the logged-in user in the group                 | `"admin"`                   |
  | `password`          | string  | Password for password-protected groups                   | `null`                      |
  | `isBannedFromGroup` | boolean | Whether the logged-in user is banned from the group      | `false`                     |
</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 provide a valid GUID for the group."` |
</Accordion>

## Get online group member count

To get the total count of online users in particular groups, you can use the `getOnlineGroupMemberCount()` method.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> guids =  [];
    guids.add("cometchat-guid-1");
    guids.add("cometchat-guid-11");

    CometChat.getOnlineGroupMemberCount(guids,
            onSuccess: (Map<String, int> count) {
          debugPrint("Fetched Online Group Member Count Successfully : $count ");
        }, onError: (CometChatException e) {
          debugPrint("Online Group Member failed with exception: ${e.message}");
        });
    ```
  </Tab>
</Tabs>

This method returns a `Map` with the GUID of the group as the key and the online member count for that group as the value.

<Accordion title="Response">
  **On Success** — A `Map<String, int>` containing the GUID of each group as the key and the online member count as the value:

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

  **Map Object:**

  | Parameter           | Type   | Description                       | Sample Value |
  | ------------------- | ------ | --------------------------------- | ------------ |
  | `cometchat-guid-1`  | number | Online member count for the group | `3`          |
  | `cometchat-guid-11` | number | Online member count for the group | `7`          |
</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="Create Group" icon="plus" href="/sdk/flutter/create-group">
    Create new public, private, or password-protected groups
  </Card>

  <Card title="Retrieve Members" icon="users" href="/sdk/flutter/retrieve-group-members">
    Get the list of members in a group
  </Card>
</CardGroup>