# Query the user list (/en/api-reference/api-ref/rtc/query-user-list)

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

Retrieves users in a specified channel.

- OpenAPI: /openapi/rtc/channel-management.en.yaml
- Operation ID: cma-query-user-list
- Method: GET
- Path: /dev/v1/channel/user/{appid}/{channelName}
- Endpoint: https://api.agora.io/dev/v1/channel/user/{appid}/{channelName}

## Servers

- https://api.agora.io

Use this endpoint to get the list of all users in a specified channel. All users in the channel must use the same channel profile; otherwise, the query results may be inaccurate.

The returned list differs based on the channel profile:
- `COMMUNICATION` profile: Returns the list of all users in the channel.
- `LIVE_BROADCASTING` profile: Returns the list of all hosts and audience members in the channel.


:::info[Note]
All users in the channel must use the same channel profile; otherwise, the query results may be inaccurate. For the `COMMUNICATION` profile, the response returns all users in the channel. For the `LIVE_BROADCASTING` profile, the response returns hosts and audience members.
:::

## Authorization

This endpoint requires authentication.

- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project. You can get it through one of the following methods:
- Copy from the [Agora Console](https://console.agora.io)
- Call the Get all projects API, and read the value of the `vendor_key`
  field in the response body.
- `channelName` (path, required, string) - The channel name.
- `hosts_only` (query, optional, string) - When specified, only the host list is returned. Applicable to the `LIVE_BROADCASTING` profile only.

### Request

- The request URL and request body is case-sensitive. All requests must use HTTPS.

- `Content-Type`: `application/json`

- The request header must contain the `Authorization` field. For details, see [RESTful authentication](/en/api-reference/api-ref/rtc/authentication).


## Request body

No request body.

## Request examples

### curl

```bash
curl --request GET \
  --url https://api.sd-rtn.com/dev/v1/channel/user/<appid>/<channelName> \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <your_base64_encoded_credentials>'
```

### Node.js

```javascript
const https = require('https');

const options = {
  method: 'GET',
  hostname: 'api.sd-rtn.com',
  port: null,
  path: '/dev/v1/channel/user/<appid>/<channelName>',
  headers: {
    Authorization: 'Basic <your_base64_encoded_credentials>',
    Accept: 'application/json'
  }
};

const req = https.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.sd-rtn.com")

headers = {
    'Authorization': "Basic <your_base64_encoded_credentials>",
    'Accept': "application/json"
}

conn.request("GET", "/dev/v1/channel/user/<appid>/<channelName>", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```


### Response

- A `200` status code indicates success. The response body contains the following parameters:

- If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. Refer to [Response status codes](/en/api-reference/api-ref/rtc/response-status-codes) for details.


## Responses

### 200

A `200` status code indicates success. The response body contains the result of the request.

- `success` (boolean) - The state of this request:
- `true`: Success.
- `false`: Reserved for future use.
- `data` (object) - User information.
  - `data.channel_exist` (boolean) - Whether the specified channel exists. When `false`, no other fields are returned.
  - `data.mode` (number) - The channel profile:
- `1`: The `COMMUNICATION` profile.
- `2`: The `LIVE_BROADCASTING` profile.
  - `data.total` (number) - The total number of users in the channel. Returned only when `mode` is `1`.
  - `data.users` (array) - User IDs of all users in the channel. Returned only when `mode` is `1`.
    - `data.users.items` (number)
  - `data.broadcasters` (array) - User IDs of all hosts in the channel. Returned only when `mode` is `2`.
    - `data.broadcasters.items` (number)
  - `data.audience` (array) - User IDs of the first 10,000 audience members in the channel. Returned only when `mode` is `2` and `hosts_only` is not specified.
    - `data.audience.items` (number)
  - `data.audience_total` (number) - The total number of audience members in the channel. Returned only when `mode` is `2` and `hosts_only` is not specified.
### default

The request failed. See the `message` field in the response body for the reason. Refer to Response status codes for details.

No schema.

### Reference

### Synchronizing channel online statistics

To synchronize online channel statistics, you can use this endpoint or the [query user status](query-user-status) endpoint. This endpoint requires a lower call frequency and offers higher efficiency, so Agora recommends it for this purpose.


## Response examples

### 200

```json
{
  "success": true,
  "data": {
    "channel_exist": true,
    "mode": 2,
    "broadcasters": [
      2206227541,
      2845863044
    ],
    "audience": [
      906219905
    ],
    "audience_total": 1
  }
}
```