# 查询用户列表 (/zh-CN/api-reference/api-ref/rtc/query-user-list)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

查询指定频道内的用户列表。

- OpenAPI: /openapi/rtc/channel-management.zh-CN.yaml
- Operation ID: get-dev-v1-channel-user-appid-channelName
- Method: GET
- Path: /dev/v1/channel/user/{appid}/{channelName}
- Endpoint: https://api.sd-rtn.com/dev/v1/channel/user/{appid}/{channelName}

## Servers

- https://api.sd-rtn.com

在不同频道场景下，该方法返回的列表具体如下：

- 通信场景下，频道内的用户列表。
- 直播场景下，频道内的主播列表和观众列表。


:::info[注意]
- 同一频道内的用户必须使用相同的频道场景。否则，查询结果可能不准确。
- 该 API 和[查询用户状态 API](query-user-status) 均能用于同步在线频道状态信息。相比于查询用户状态 API，该 API 所需的调用频率低，查询效率高。因此，声网更推荐使用该 API 查询用户状态。
:::

## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `appid` (path, required) - 项目的 App ID。可通过以下方式获取：
- 从声网控制台获取。
- 调用[获取所有项目信息 API](/zh-CN/api-reference/api-ref/console/list-projects)，并读取响应包体中 `vendor_key` 字段的值。
- `channelName` (path, required) - 频道名称。

## Request body

No request body.

## Responses

### 200

如果状态码为 200，则请求成功。

- `success` (boolean) - 本次请求的状态：
- `true`：请求成功
- `false`：预留
- `data` (object)
  - `data.channel_exist` (boolean) - 指定频道是否存在：
- `true`：存在
- `false`：不存在

注意：当 `channel_exist` 的值为 `false` 时，不会返回其它字段。
  - `data.mode` (number) - 频道场景：
- `1`：通信场景
- `2`：直播场景
  - `data.total` (number) - 频道内的总人数。该字段仅在通信场景（`mode` 的值为 `1` ）下返回。
  - `data.users` (array) - 频道内所有用户的用户 ID。该字段仅在通信场景（`mode` 的值为 `1`）下返回。
    - `data.users.items` (integer)
  - `data.broadcasters` (array) - 频道内所有主播的用户 ID。该字段仅在直播场景（`mode` 的值为 `2`）下返回。
    - `data.broadcasters.items` (integer)
  - `data.audience` (array) - 频道内观众的用户 ID。最多包含当前频道内前 10,000 名观众的用户 ID。该字段仅在直播场景（`mode` 的值为 2）且未填 `hosts_only` 参数时返回。
    - `data.audience.items` (integer)
  - `data.audience_total` (number) - 频道内的观众总人数。该字段仅在直播场景（`mode` 的值为 `2`）下且未填 `hosts_only` 参数时返回。
### 非 200

如果状态码不为 200，则请求失败。你可以参考[响应状态码](/zh-CN/realtime-media/rtc/reference/response-code)排查问题。

No schema.

## Response examples

### 200

```json
{
  "success": true,
  "data": {
    "channel_exist": true,
    "mode": 1,
    "total": 1,
    "users": [
      906218805
    ]
  }
}
```