> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# List Groups

> Returns all groups the instance belongs to

**Auth:** `TokenAccount` or `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotent:** yes

## Description

Lists every group the instance belongs to. By default, only lightweight metadata is returned (name, JID, description, creator, count). Pass `includeMembers=true` in the query to include the full member list, when you do, the operation timeout is extended to **60s**.

## Examples

### List (without members)

Returns every group of the instance with lightweight metadata only (name, JID, description, creator, count). This is the default mode and the fastest for accounts with many groups.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/group/list/$Instance_Name" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://ryzeapi.cloud/api/group/list/${process.env.Instance_Name}`, {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      f"https://ryzeapi.cloud/api/group/list/{os.environ['Instance_Name']}",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/group/list/"+os.Getenv("Instance_Name"), nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### List with members

Add `includeMembers=true` to include the full participant list of every group. The internal timeout is extended to 60s, useful when you need a complete snapshot in a single call.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/group/list/$Instance_Name?includeMembers=true" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://ryzeapi.cloud/api/group/list/${process.env.Instance_Name}?includeMembers=true`, {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      f"https://ryzeapi.cloud/api/group/list/{os.environ['Instance_Name']}?includeMembers=true",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/group/list/"+os.Getenv("Instance_Name")+"?includeMembers=true", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Success response

Returns every group of the instance under `groups[]`, with `meta.total` reporting the count. Each item carries lightweight metadata (`name`, `groupJid`, `description`, `creatorJid`, `memberCount`); the `members` array is populated only when `includeMembers=true`. There is no pagination, every group comes in a single response.

```json 200 OK theme={null}
{
  "success": true,
  "message": "2 Groups found",
  "groups": [
    {
      "name": "Dev Team",
      "groupJid": "120363406289005073@g.us",
      "description": "Technical discussions",
      "creatorJid": "5511999999999@s.whatsapp.net",
      "memberCount": 3,
      "members": [
        { "jid": "5511999999999@s.whatsapp.net", "isAdmin": true, "isSuperAdmin": false }
      ]
    }
  ],
  "meta": { "total": 2 }
}
```

## Path parameters

<ParamField path="instance" type="string" required>
  Instance name.
</ParamField>

## Headers

<ParamField header="token" type="string" required>
  `TokenAccount` or `TokenInstance`.
</ParamField>

## Query

<ParamField query="includeMembers" type="boolean" default="false">
  When `true`, includes the full member list of each group.
</ParamField>

## Notes

<Note>
  * The `members` array only appears when `includeMembers=true`.
  * For accounts with many groups, use `includeMembers=false` and fetch members on demand via [`GET /info`](/en/api/groups/info).
  * There is no pagination, every group comes in a single response.
</Note>

## Errors

| HTTP | Message                                 |
| ---- | --------------------------------------- |
| 400  | `Instance is not connected to WhatsApp` |
| 404  | `Instance not found`                    |

Envelope:

```json theme={null}
{
  "success": false,
  "error": { "message": "Instance is not connected to WhatsApp" }
}
```