# Query the list of user groups

Call this interface to query the list of user groups under the current tenant. The list contains information such as the ID, name, number and type of members of the user group.

## Precautions

- If the application's contacts permission scope is set to **All members**, then the information of all user groups in the tenant can be queried through this interface. Otherwise, only the user group information within the application contacts permission range will be queried. To understand the permission scope of the application contacts, please refer to [Permission Scope Resource Introduction](https://open.feishu.cn/document/ukTMukTMukTM/uETNz4SM1MjLxUzM/v3/guides/scope_authority).

- Supports querying information about ordinary user groups and dynamic user groups.

## Request

Facts |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/contact/v3/group/simplelist
HTTP Method | GET
Rate Limit | [1000 per minute & 50 per second](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App、Store App
Required scopes<br>**To use this API, you must have at least 1 of the listed scopes.** | Obtain user group information(contact:group:readonly)

### Request header

Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `tenant_access_token`<br>**Value format**: "Bearer `access_token`"<br>**Example value**: "Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>[How to choose and get access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)

### Query parameters

Parameter | Type | Required | Description
---|---|---|---
page_size | int | No | Paging size, used to limit the number of data entries returned in one request.<br>**Example value**: 50<br>**Default value**: `50`<br>**Data validation rules**:<br>- Maximum value: `100`
page_token | string | No | Page identifier. It is not filled in the first request, indicating traversal from the beginning; when there will be more groups, the new page_token will be returned at the same time, and the next traversal can use the page_token to get more groups<br>**Example value**: AQD9/Rn9eij9Pm39ED40/dk53s4Ebp882DYfFaPFbz00L4CMZJrqGdzNyc8BcZtDbwVUvRmQTvyMYicnGWrde9X56TgdBuS+JKiSIkdexPw=
type | int | No | User group type.<br>**Example value**: 1<br>**Optional values are**:<br>- 1：Common user group<br>- 2：Dynamic user group<br>**Default value**: `1`

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
grouplist | group\[\] | List of user groups.
id | string | User group ID, which can be used to delete, update, and query user groups.
name | string | User group name.
description | string | User group description.
member_user_count | int | Number of users among user group members.
member_department_count | int | The number of departments among members of the common user group.<br>**Note**: There are no departments among the members of the dynamic user group.
type | int | Type of user group.<br>**Optional values are**:<br>- 1：General user group<br>- 2：Dynamic user group
department_scope_list | string\[\] | Department scope, displayed as a list of department IDs.
group_id | string | Custom user group ID.
page_token | string | Page identifier, when has_more is true, a new page_token will also be returned. Otherwise, page_token will not be returned
has_more | boolean | Whether the response body has more parameters

### Response body example
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "grouplist": [
            {
                "id": "g193821",
                "name": "IT outsourcing group",
                "description": "IT outsourcing group. Fine-grained permission control is required for this group.",
                "member_user_count": 2,
                "member_department_count": 0,
                "type": 1,
                "department_scope_list": [
                    "od-4e6ac4d14bcd5071a37a39de902c7141"
                ],
                "group_id": "4ba51ab38648f9cd"
            }
        ],
        "page_token": "AQD9/Rn9556539ED40/dk53s4Ebp882DYfFaPFbz00L4CMZJrqGdzNyc8BcZtDbwVUvRmQTvyMYicnGWrde9X56TgdBuS+JDTJJDDPw=",
        "has_more": true
    }
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
500 | 40003 | internal error | Internal error, you can get the X-Request-Id of the request and contact [Technical Support](https://applink.feishu.cn/TLJpeNdW).
400 | 40011 | page size is invalid | page_size is invalid. The value range of page_size is 1 ~ 100. Please adjust the parameter value and try again.
400 | 40012 | page token is invalid error | page_token is invalid. You need to check whether the page_token passed in is the page_token value returned by the last request.

For more error code information, see [General error codes](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN).