Query the user list
Updated
Retrieves users in a specified channel.
https://api.agora.io/dev/v1/channel/user/{appid}/{channelName}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:
COMMUNICATIONprofile: Returns the list of all users in the channel.LIVE_BROADCASTINGprofile: Returns the list of all hosts and audience members in the channel.
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.
Path Parameters
appidstringThe App ID of the project. You can get it through one of the following methods:
- Copy from the Agora Console
- Call the Get all projects API, and read the value of the
vendor_keyfield in the response body.
channelNamestringThe channel name.
Query Parameters
hosts_onlystringWhen 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
Authorizationfield. For details, see RESTful authentication.
Response
-
A
200status code indicates success. The response body contains the following parameters: -
If the status code is not
200, the request fails. See themessagefield in the response body for the reason for this failure. Refer to Response status codes for details.
Response Body
A 200 status code indicates success. The response body contains the result of the request.
successbooleanThe state of this request:
true: Success.false: Reserved for future use.
dataobjectUser information.
channel_existbooleanWhether the specified channel exists. When false, no other fields are returned.
modenumberThe channel profile:
1: TheCOMMUNICATIONprofile.2: TheLIVE_BROADCASTINGprofile.
totalnumberThe total number of users in the channel. Returned only when mode is 1.
usersarray<number>User IDs of all users in the channel. Returned only when mode is 1.
broadcastersarray<number>User IDs of all hosts in the channel. Returned only when mode is 2.
audiencearray<number>User IDs of the first 10,000 audience members in the channel. Returned only when mode is 2 and hosts_only is not specified.
audience_totalnumberThe total number of audience members in the channel. Returned only when mode is 2 and hosts_only is not specified.
Reference
Synchronizing channel online statistics
To synchronize online channel statistics, you can use this endpoint or the query user status endpoint. This endpoint requires a lower call frequency and offers higher efficiency, so Agora recommends it for this purpose.
Request examples
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>'Response example
{ "success": true, "data": { "channel_exist": true, "mode": 2, "broadcasters": [ 2206227541, 2845863044 ], "audience": [ 906219905 ], "audience_total": 1 }}