> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt?lang=zh
> Use this file to discover all available pages before exploring further.

分页获取企业成员列表，可按部门与账号类型过滤。

## 所需权限 {#d65130b8}

`users:read`

## 请求说明 {#cd6fa3a3}

* 请求方式：`GET`
* 请求地址：`{域名}/openapi/v1/users`

## 请求参数 {#请求参数}

### 请求头参数 {#请求头参数}

<!-- @cols-width: 172,122,596 -->
| **Header 参数**  | **是否必填**  | **描述**  |
| --- | --- | --- |
| `Authorization`  | 是  | 固定取值为 `Bearer {access_token}`。关于如何获取访问令牌，参考[鉴权](enterprise_authentication)。  |

### 查询参数 {#03592c99}

<!-- @cols-width: 146,115,103,101,447 -->
| **参数**  | **类型**  | **是否必填**  | **默认值**  | **描述**  |
| --- | --- | --- | --- | --- |
| `page`  | int  | 否  | `1`  | 需返回的页数。  |
| `page_size`  | int  | 否  | `100`  | 每页返回的成员数量，最多 500 个。  |
| `account_type`  | int  | 否  | \-  | 账号类型，用于按账号类型筛选成员： | \
| | | | | | \
| | | | | * `1`：全端账号 | \
| | | | | * `2`：Work 专属账号 | \
| | | | | | \
| | | | | 若省略该参数，则返回全部账号类型的成员。  |
| `department_id`  | string  | 否  | \-  | 目标部门的 ID，用于按部门筛选成员。  |
| `include_subtree`  | bool  | 否  | `true`  | 是否包含目标部门的子部门的成员。 | \
| | | | | | \
| | | | | * `true`：包含 | \
| | | | | * `false`：不包含 | \
| | | | | | \
| | | | | 该参数仅在传入 `department_id` 参数时生效。若省略，则返回全部子部门的成员。  |
| `include_removed`  | bool  | 否  | `false`  | 是否包含已移除的成员： | \
| | | | | | \
| | | | | * `true`：同时返回当前仍在企业中的成员和已被移除的成员。 | \
| | | | | * `false`：仅返回当前仍在企业中的成员  |

## 响应参数 {#f2d8ac3a}

该接口独有的响应参数如下，参数位于 `data` 中。通用响应参数参考[此文档](/enterprise_general-response-schema)。

<!-- @cols-width: 286,149,461 -->
| **参数**  | **类型**  | **描述**  |
| --- | --- | --- |
| `items`  | array  | 成员信息列表。  |
| `items[].user_id`  | int64  | 成员的 ID。  |
| `items[].user_id_str`  | string  | 成员 ID 的字符串形式。  |
| `items[].user_name`  | string  | 成员的名称。  |
| `items[].email`  | string  | 成员的邮箱。  |
| `items[].role`  | string  | 成员的角色： | \
| | | | \
| | | * `super_admin`：超级管理员 | \
| | | * `admin`：管理员 | \
| | | * `member`：成员  |
| `items[].status`  | string  | 成员的状态： | \
| | | | \
| | | * `active`：账号/席位使用中 | \
| | | * `added`：已加入但未激活 | \
| | | * `pending`：邀请中 | \
| | | * `removed`：已移除（仅可能在 `include_removed=true` 时返回）  |
| `items[].join_time`  | int64  | 成员加入企业的时间（毫秒时间戳）。  |
| `items[].account_type`  | int  | 成员的账号类型： | \
| | | | \
| | | * `1`：全端账号 | \
| | | * `2`：Work 专属账号 | \
| | | | \
| | | ***提示***：旧旗舰版套餐仅支持全端账号。  |
| `items[].departments`  | array  | 成员直属部门信息列表。  |
| `items[].departments[].department_id`  | string  | 直属部门的 ID。  |
| `items[].departments[].name`  | string  | 直属部门的名称。  |
| `items[].departments[].full_path`  | string  | 直属部门的完整路径。各级部门名称以 `/` 分隔。  |

## 示例 {#示例}

### 请求示例 {#ee38dfa2}

```Bash
curl -X GET "${HOST}/openapi/v1/users?page=1&page_size=100&department_id=20001&include_subtree=false" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
```

### 响应示例 {#97f43d34}

```JSON
{
  "code": 0,
  "message": "success",
  "request_id": "req_xxx",
  "data": {
    "items": [
      {
        "user_id": 123456,
        "user_id_str": "123456",
        "user_name": "Alice",
        "email": "alice@example.com",
        "role": "member",
        "status": "added",
        "join_time": 1700000000000,
        "account_type": 1,
        "departments": [
          {
            "department_id": "10001",
            "name": "研发部",
            "full_path": "公司/研发部"
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total": 1,
      "total_pages": 1
    }
  }
}
```

## 错误码 {#错误码}

若该接口的请求返回错误码，参考[错误码](/enterprise_error-codes)文档进行排查。