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

# Retrieve Groups

> Fetch group lists, search groups, get group details, and retrieve online member counts using the CometChat React Native SDK.

<Info>
  **Quick Reference** - Fetch groups:

  ```javascript theme={null}
  // Fetch group list
  const groupsRequest = new CometChat.GroupsRequestBuilder().setLimit(30).build();
  const groups = await groupsRequest.fetchNext();

  // Get specific group
  const group = await CometChat.getGroup("GUID");

  // Get online member count
  const counts = await CometChat.getOnlineGroupMemberCount(["GUID"]);
  ```
</Info>

<Note>
  **Available via:** [SDK](/sdk/react-native/retrieve-groups) | [REST API](/rest-api/groups/list) | [UI Kits](/ui-kit/react-native/groups)
</Note>

## Overview

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

## GroupsRequestBuilder

The `GroupsRequestBuilder` class allows you to set the below parameters:

### Set Limit

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

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    let limit = 30;
    let groupsRequest = new CometChat.GroupsRequestBuilder()
      .setLimit(limit)
      .build();
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let limit: number = 30;
    let groupsRequest: CometChat.GroupsRequest =
      new CometChat.GroupsRequestBuilder().setLimit(limit).build();
    ```
  </Tab>
</Tabs>

<Accordion title="Response">
  **On Success** — `fetchNext()` with basic limit returns an array of `Group` objects:

  | Parameter        | Type    | Description                                          | Sample Value                        |
  | ---------------- | ------- | ---------------------------------------------------- | ----------------------------------- |
  | `guid`           | string  | Unique identifier of the group                       | `"007007"`                          |
  | `name`           | string  | Display name of the group                            | `"Bond"`                            |
  | `type`           | string  | Group type (public, private, password)               | `"public"`                          |
  | `owner`          | string  | UID of the group owner                               | `"user-b"`                          |
  | `membersCount`   | number  | Total number of members in the group                 | `5`                                 |
  | `hasJoined`      | boolean | Whether the logged-in user has joined this group     | `false`                             |
  | `isBanned`       | boolean | Whether the logged-in user is banned from this group | `false`                             |
  | `conversationId` | string  | Conversation ID for this group                       | `"group_007007"`                    |
  | `createdAt`      | number  | Unix timestamp when group was created                | `1760001806`                        |
  | `updatedAt`      | number  | Unix timestamp of last update                        | `1768398330`                        |
  | `updatedBy`      | string  | UID of user who last updated the group (if updated)  | `"123456"`                          |
  | `description`    | string  | Group description (if set)                           | `"Testing group for QA users"`      |
  | `icon`           | string  | URL to group icon image (if set)                     | `"https://images.unsplash.com/..."` |
</Accordion>

### Set Search Keyword

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

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    let limit = 30;
    let searchKeyword = "group";
    let groupsRequest = new CometChat.GroupsRequestBuilder()
      .setLimit(limit)
      .setSearchKeyword(searchKeyword)
      .build();
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let limit: number = 30;
    let searchKeyword: string = "group";
    let groupsRequest: CometChat.GroupsRequest =
      new CometChat.GroupsRequestBuilder()
        .setLimit(limit)
        .setSearchKeyword(searchKeyword)
        .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Response">
  **On Success** — `fetchNext()` with search filter returns an array of `Group` objects matching the keyword:

  | Parameter        | Type    | Description                                          | Sample Value                        |
  | ---------------- | ------- | ---------------------------------------------------- | ----------------------------------- |
  | `guid`           | string  | Unique identifier of the group                       | `"group_1748350143247"`             |
  | `name`           | string  | Display name of the group                            | `"testmemebrrole"`                  |
  | `type`           | string  | Group type (public, private, password)               | `"public"`                          |
  | `owner`          | string  | UID of the group owner                               | `"123456"`                          |
  | `membersCount`   | number  | Total number of members in the group                 | `7`                                 |
  | `hasJoined`      | boolean | Whether the logged-in user has joined this group     | `false`                             |
  | `isBanned`       | boolean | Whether the logged-in user is banned from this group | `false`                             |
  | `conversationId` | string  | Conversation ID for this group                       | `"group_group_1748350143247"`       |
  | `createdAt`      | number  | Unix timestamp when group was created                | `1748350143`                        |
  | `updatedAt`      | number  | Unix timestamp of last update                        | `1768888876`                        |
  | `description`    | string  | Group description (if set)                           | `"Testing group for QA users"`      |
  | `icon`           | string  | URL to group icon image (if set)                     | `"https://images.unsplash.com/..."` |
</Accordion>

### Joined Only

This method when used, will ask the SDK to only return the groups that the user has joined or is a part of.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    let limit = 30;
    let groupsRequest = new CometChat.GroupsRequestBuilder()
      .setLimit(limit)
      .joinedOnly(true)
      .build();
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let limit: number = 30;
    let groupsRequest: CometChat.GroupsRequest =
      new CometChat.GroupsRequestBuilder().setLimit(limit).joinedOnly(true).build();
    ```
  </Tab>
</Tabs>

<Accordion title="Response">
  **On Success** — `fetchNext()` with `joinedOnly(true)` returns groups the user has joined, with additional fields:

  | Parameter            | Type    | Description                                                    | Sample Value                        |
  | -------------------- | ------- | -------------------------------------------------------------- | ----------------------------------- |
  | `guid`               | string  | Unique identifier of the group                                 | `"tg1"`                             |
  | `name`               | string  | Display name of the group                                      | `"Touring Group"`                   |
  | `type`               | string  | Group type (public, private, password)                         | `"public"`                          |
  | `owner`              | string  | UID of the group owner                                         | `"app_system"`                      |
  | `membersCount`       | number  | Total number of members in the group                           | `2`                                 |
  | `hasJoined`          | boolean | Whether the logged-in user has joined this group               | `true`                              |
  | `isBanned`           | boolean | Whether the logged-in user is banned from this group           | `false`                             |
  | `scope`              | string  | User's scope/role in the group (participant, admin, moderator) | `"participant"`                     |
  | `joinedAt`           | number  | Unix timestamp when user joined the group                      | `1771829827`                        |
  | `onlineMembersCount` | number  | Number of online members in the group                          | `2`                                 |
  | `conversationId`     | string  | Conversation ID for this group                                 | `"group_tg1"`                       |
  | `createdAt`          | number  | Unix timestamp when group was created                          | `1771829812`                        |
  | `updatedAt`          | number  | Unix timestamp of last update                                  | `1771829832`                        |
  | `icon`               | string  | URL to group icon image (if set)                               | `"https://static.vecteezy.com/..."` |
</Accordion>

### Set Tags

This method accepts a list of tags based on which the list of groups is to be fetched. The list fetched will only contain the groups that have been tagged with the specified tags.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    let limit = 30;
    let tags = ["tag1", "tag2"];
    let groupsRequest = new CometChat.GroupsRequestBuilder()
      .setLimit(limit)
      .setTags(tags)
      .build();
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let limit: number = 30;
    let tags: Array<String> = ["tag1", "tag2"];
    let groupsRequest: CometChat.GroupsRequest =
      new CometChat.GroupsRequestBuilder().setLimit(limit).setTags(tags).build();
    ```
  </Tab>
</Tabs>

<Accordion title="Response">
  **On Success** — `fetchNext()` with tags filter returns groups matching the specified tags:

  | Parameter        | Type    | Description                                          | Sample Value                    |
  | ---------------- | ------- | ---------------------------------------------------- | ------------------------------- |
  | `guid`           | string  | Unique identifier of the group                       | `"group_1748264644578"`         |
  | `name`           | string  | Display name of the group                            | `"Password123NameChangedAgain"` |
  | `type`           | string  | Group type (public, private, password)               | `"password"`                    |
  | `owner`          | string  | UID of the group owner                               | `"123456"`                      |
  | `membersCount`   | number  | Total number of members in the group                 | `2`                             |
  | `hasJoined`      | boolean | Whether the logged-in user has joined this group     | `false`                         |
  | `isBanned`       | boolean | Whether the logged-in user is banned from this group | `false`                         |
  | `conversationId` | string  | Conversation ID for this group                       | `"group_group_1748264644578"`   |
  | `createdAt`      | number  | Unix timestamp when group was created                | `1748264644`                    |
  | `updatedAt`      | number  | Unix timestamp of last update                        | `1768888876`                    |
  | `updatedBy`      | string  | UID of user who last updated the group               | `"123456"`                      |
</Accordion>

### With Tags

This property when set to true will fetch tags data along with the list of groups.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    let limit = 30;
    let groupsRequest = new CometChat.GroupsRequestBuilder()
      .setLimit(limit)
      .withTags(true)
      .build();
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let limit: number = 30;
    let groupsRequest: CometChat.GroupsRequest =
      new CometChat.GroupsRequestBuilder().setLimit(limit).withTags(true).build();
    ```
  </Tab>
</Tabs>

<Accordion title="Response">
  **On Success** — `fetchNext()` with `withTags(true)` returns groups including the `tags` field:

  | Parameter        | Type    | Description                                          | Sample Value      |
  | ---------------- | ------- | ---------------------------------------------------- | ----------------- |
  | `guid`           | string  | Unique identifier of the group                       | `"courses"`       |
  | `name`           | string  | Display name of the group                            | `"Courses"`       |
  | `type`           | string  | Group type (public, private, password)               | `"public"`        |
  | `owner`          | string  | UID of the group owner                               | `"app_system"`    |
  | `membersCount`   | number  | Total number of members in the group                 | `4`               |
  | `hasJoined`      | boolean | Whether the logged-in user has joined this group     | `false`           |
  | `isBanned`       | boolean | Whether the logged-in user is banned from this group | `false`           |
  | `tags`           | array   | Tags associated with the group                       | `["courses"]`     |
  | `conversationId` | string  | Conversation ID for this group                       | `"group_courses"` |
  | `createdAt`      | number  | Unix timestamp when group was created                | `1764919309`      |
  | `updatedAt`      | number  | Unix timestamp of last update                        | `1764929127`      |
</Accordion>

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` objects containing n number of groups where n is the limit set in the builder class.

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 the group.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    let limit = 30;
    let groupsRequest = new CometChat.GroupsRequestBuilder()
      .setLimit(limit)
      .build();

    groupsRequest.fetchNext().then(
      (groupList) => {
        console.log("Groups list fetched successfully", groupList);
      },
      (error) => {
        console.log("Groups list fetching failed with error", error);
      }
    );
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let limit: number = 30;
    let groupsRequest: CometChat.GroupsRequest =
      new CometChat.GroupsRequestBuilder().setLimit(limit).build();

    groupsRequest.fetchNext().then(
      (groupList: CometChat.Group[]) => {
        console.log("Groups list fetched successfully", groupList);
      },
      (error: CometChat.CometChatException) => {
        console.log("Groups list fetching failed with error", error);
      }
    );
    ```
  </Tab>
</Tabs>

<Accordion title="Response">
  **On Success** — `fetchNext()` returns an array of `Group` objects. See the filter-specific Response accordions above for field details based on your query configuration.
</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="JavaScript">
    ```javascript theme={null}
    var GUID = "GUID";
    CometChat.getGroup(GUID).then(
      (group) => {
        console.log("Group details fetched successfully:", group);
      },
      (error) => {
        console.log("Group details fetching failed with exception:", error);
      }
    );
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    var GUID: string = "GUID";
    CometChat.getGroup(GUID).then(
      (group: CometChat.Group) => {
        console.log("Group details fetched successfully:", group);
      },
      (error: CometChat.CometChatException) => {
        console.log("Group details fetching failed with exception:", error);
      }
    );
    ```
  </Tab>
</Tabs>

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

<Accordion title="Response">
  **On Success** — `getGroup()` returns a `Group` object:

  | Parameter        | Type    | Description                                          | Sample Value     |
  | ---------------- | ------- | ---------------------------------------------------- | ---------------- |
  | `guid`           | string  | Unique identifier of the group                       | `"007007"`       |
  | `name`           | string  | Display name of the group                            | `"Bond"`         |
  | `type`           | string  | Group type (public, private, password)               | `"public"`       |
  | `owner`          | string  | UID of the group owner                               | `"user-b"`       |
  | `membersCount`   | number  | Total number of members in the group                 | `5`              |
  | `hasJoined`      | boolean | Whether the logged-in user has joined this group     | `false`          |
  | `isBanned`       | boolean | Whether the logged-in user is banned from this group | `false`          |
  | `conversationId` | string  | Conversation ID for this group                       | `"group_007007"` |
  | `createdAt`      | number  | Unix timestamp when group was created                | `1760001806`     |
  | `updatedAt`      | number  | Unix timestamp of last update                        | `1768398330`     |
</Accordion>

It returns `Group` object containing the details of the group.

## 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="JavaScript">
    ```javascript theme={null}
    let guids = ["cometchat-guid-1"];
    CometChat.getOnlineGroupMemberCount(guids).then(
      (groupMemberCount) => {
        console.log("Total online user for specified groups:", groupMemberCount);
      },
      (error) => {
        console.log("Online group member count fetching failed with error:", error);
      }
    );
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    let guids: String[] = ["cometchat-guid-1"];
    CometChat.getOnlineGroupMemberCount(guids).then(
      (groupMemberCount: number) => {
        console.log("Total online user for specified groups:", groupMemberCount);
      },
      (error: CometChat.CometChatException) => {
        console.log("Online group member count fetching failed with error:", error);
      }
    );
    ```
  </Tab>
</Tabs>

<Accordion title="Response">
  **On Success** — `getOnlineGroupMemberCount()` returns an object with GUID as key and online count as value:

  | Parameter | Type   | Description                                 | Sample Value |
  | --------- | ------ | ------------------------------------------- | ------------ |
  | `[GUID]`  | number | Online member count for the specified group | `0`          |

  Example: `{"tg1": 2}`
</Accordion>

This method returns a JSON Object with the GUID as the key and the online member count for that group as the value.

## Best Practices

<AccordionGroup>
  <Accordion title="Use pagination for large group lists">
    Always use `fetchNext()` with a reasonable `setLimit()` value (e.g., 20-30) rather than fetching all groups at once. This improves performance and reduces memory usage.
  </Accordion>

  <Accordion title="Reuse the same GroupsRequest instance for pagination">
    The `GroupsRequest` object maintains an internal cursor. Creating a new instance resets the cursor, causing the same page to be fetched repeatedly. Reuse the same instance across `fetchNext()` calls.
  </Accordion>

  <Accordion title="Use joinedOnly for user-specific views">
    When displaying "My Groups" in your UI, use `joinedOnly(true)` to fetch only groups the user belongs to, rather than filtering the full list client-side.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Private groups not appearing in list">
    Private groups are only returned if the logged-in user is a member. This is by design — use `joinedOnly(true)` to see all groups the user has access to, including private ones.
  </Accordion>

  <Accordion title="fetchNext returns empty list">
    Verify the logged-in user session is active. Also check if filters like `setTags` or `setSearchKeyword` are too restrictive. Try removing filters to confirm groups exist.
  </Accordion>

  <Accordion title="getGroup returns error">
    Ensure the GUID exists in your CometChat app. GUIDs are case-sensitive — double-check the exact GUID string.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Group" icon="plus" href="/sdk/react-native/create-group">
    Create public, private, or password-protected groups
  </Card>

  <Card title="Join a Group" icon="right-to-bracket" href="/sdk/react-native/join-group">
    Join public or password-protected groups
  </Card>

  <Card title="Group Members" icon="users" href="/sdk/react-native/group-members">
    Manage members, roles, and permissions within groups
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/sdk/react-native/send-message">
    Send text, media, and custom messages to groups
  </Card>
</CardGroup>