Query user list

This method gets the list of all users in a specified channel.

• Method: GET
• Endpoint: https://api.agora.io/dev/v1/channel/user/{appid}/{channelName}

The return list differs based on the channel profile as follows:

• For the COMMUNICATION profile, this API returns the list of all users in the channel.
• For the LIVE_BROADCASTING profile, this API returns the list of all hosts and audience members in the channel.

Note

• Users in a channel must use the same channel profile; otherwise, the query results may be inaccurate.
• You can synchronize the online channel statistics either by calling this API or by calling the Query user status API. This API requires a lower call frequency and has a higher query efficiency. Therefore, Agora recommends using this API to query online channel statistics.

Path parameters

Pass the following path parameters in the request URL:

Parameter	Type	Required/Optional	Description
appid	String	Required	The 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_key field in the response body.
channelName	String	Required	The channel name.
hosts_only	String	Optional	If you fill in this parameter, only the host list in the live broadcast scenario will be returned.

Request header

The Content-Type field in all HTTP request headers is application/json. All requests and responses are in JSON format. All request URLs and request bodies are case-sensitive.

The Agora Channel Management RESTful APIs only support HTTPS. Before sending HTTP requests, you must generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora, and pass the credential to the Authorization field in the HTTP request header. See RESTful authentication for details.

Test this request in Postman or use one of the following code examples:

Shell

• curl

  curl --request GET \  --url http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only \  --header 'Accept: application/json' \  --header 'Authorization: '
• HTTPie

  http GET http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only \  Accept:application/json \  Authorization:''\
• wget

  wget --quiet \  --method GET \  --header 'Authorization: '\  --header 'Accept: application/json' \  --output-document \  - http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only

Javascript

• Fetch

  const url = 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only';const options = {method: 'GET', headers: {Authorization: '', Accept: 'application/json'}};try {  const response = await fetch(url, options);  const data = await response.json();  console.log(data);} catch (error) {  console.error(error);}
• XMLHTTPRequest

  const data = null;const xhr = new XMLHttpRequest();xhr.withCredentials = true;xhr.addEventListener('readystatechange', function () {  if (this.readyState === this.DONE) {    console.log(this.responseText);  }});xhr.open('GET', 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only');xhr.setRequestHeader('Authorization', '');xhr.setRequestHeader('Accept', 'application/json');xhr.send(data);
• jQuery

  const settings = {  async: true,  crossDomain: true,  url: 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only',  method: 'GET',  headers: {    Authorization: '',    Accept: 'application/json'  }};$.ajax(settings).done(function (response) {  console.log(response);});
• Axios

  import axios from 'axios';const options = {  method: 'GET',  url: 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only',  headers: {Authorization: '', Accept: 'application/json'}};try {  const { data } = await axios.request(options);  console.log(data);} catch (error) {  console.error(error);}

Node

• Native

  const http = require('http');const options = {  method: 'GET',  hostname: 'api.sd-rtn.com',  port: null,  path: '/dev/v1/channel/user/appid/channelName/hosts_only',  headers: {    Authorization: '',    Accept: 'application/json'  }};const req = http.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();
• Request

  const request = require('request');const options = {  method: 'GET',  url: 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only',  headers: {Authorization: '', Accept: 'application/json'}};request(options, function (error, response, body) {  if (error) throw new Error(error);  console.log(body);});
• Unirest

  const unirest = require('unirest');const req = unirest('GET', 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only');req.headers({  Authorization: '',  Accept: 'application/json'});req.end(function (res) {  if (res.error) throw new Error(res.error);  console.log(res.body);});
• Fetch

  const fetch = require('node-fetch');const url = 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only';const options = {method: 'GET', headers: {Authorization: '', Accept: 'application/json'}};try {  const response = await fetch(url, options);  const data = await response.json();  console.log(data);} catch (error) {  console.error(error);}
• Axios

  const axios = require('axios').default;const options = {  method: 'GET',  url: 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only',  headers: {Authorization: '', Accept: 'application/json'}};try {  const { data } = await axios.request(options);  console.log(data);} catch (error) {  console.error(error);}

Python

• Python 3

  import http.clientconn = http.client.HTTPConnection("api.sd-rtn.com")headers = {    'Authorization': "",    'Accept': "application/json"}conn.request("GET", "/dev/v1/channel/user/appid/channelName/hosts_only", headers=headers)res = conn.getresponse()data = res.read()print(data.decode("utf-8"))
• Requests

  import requestsurl = "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only"headers = {    "Authorization": "",    "Accept": "application/json"}response = requests.get(url, headers=headers)print(response.json())

Go

package mainimport (  "fmt"  "net/http"  "io")func main() {  url := "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only"  req, _ := http.NewRequest("GET", url, nil)  req.Header.Add("Authorization", "")  req.Header.Add("Accept", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := io.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

C

CURL *hnd = curl_easy_init();curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");curl_easy_setopt(hnd, CURLOPT_URL, "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only");struct curl_slist *headers = NULL;headers = curl_slist_append(headers, "Authorization: ");headers = curl_slist_append(headers, "Accept: application/json");curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);CURLcode ret = curl_easy_perform(hnd);

Objective-C

#import <Foundation/Foundation.h>NSDictionary *headers = @{ @"Authorization": @"",                           @"Accept": @"application/json" };NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only"]                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy                                                   timeoutInterval:10.0];[request setHTTPMethod:@"GET"];[request setAllHTTPHeaderFields:headers];NSURLSession *session = [NSURLSession sharedSession];NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {                                                if (error) {                                                    NSLog(@"%@", error);                                                } else {                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;                                                    NSLog(@"%@", httpResponse);                                                }                                            }];[dataTask resume];

OCaml

open Cohttp_lwt_unixopen Cohttpopen Lwtlet uri = Uri.of_string "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only" inlet headers = Header.add_list (Header.init ()) [  ("Authorization", "");  ("Accept", "application/json");] inClient.call ~headers `GET uri>>= fun (res, body_stream) ->  (* Do stuff with the result *)

C#

• HTTPClient

  using System.Net.Http.Headers;var client = new HttpClient();var request = new HttpRequestMessage{    Method = HttpMethod.Get,    RequestUri = new Uri("http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only"),    Headers =    {        { "Authorization", "" },        { "Accept", "application/json" },    },};using (var response = await client.SendAsync(request)){    response.EnsureSuccessStatusCode();    var body = await response.Content.ReadAsStringAsync();    Console.WriteLine(body);}
• RestSharp

  var client = new RestClient("http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only");var request = new RestRequest(Method.GET);request.AddHeader("Authorization", "");request.AddHeader("Accept", "application/json");IRestResponse response = client.Execute(request);

Java

• AsyncHttp

  AsyncHttpClient client = new DefaultAsyncHttpClient();client.prepare("GET", "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only")  .setHeader("Authorization", "")  .setHeader("Accept", "application/json")  .execute()  .toCompletableFuture()  .thenAccept(System.out::println)  .join();client.close();
• NetHttp

  HttpRequest request = HttpRequest.newBuilder()    .uri(URI.create("http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only"))    .header("Authorization", "")    .header("Accept", "application/json")    .method("GET", HttpRequest.BodyPublishers.noBody())    .build();HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());
• OkHttp

  OkHttpClient client = new OkHttpClient();Request request = new Request.Builder()  .url("http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only")  .get()  .addHeader("Authorization", "")  .addHeader("Accept", "application/json")  .build();Response response = client.newCall(request).execute();
• Unirest

  HttpResponse<String> response = Unirest.get("http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only")  .header("Authorization", "")  .header("Accept", "application/json")  .asString();

Http 1.1

GET /dev/v1/channel/user/appid/channelName/hosts_only HTTP/1.1Authorization:Accept: application/jsonHost: api.sd-rtn.com

Clojure

(require '[clj-http.client :as client])(client/get "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only" {:headers {:Authorization ""}                                                                                      :accept :json})

Kotlin

val client = OkHttpClient()val request = Request.Builder()  .url("http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only")  .get()  .addHeader("Authorization", "")  .addHeader("Accept", "application/json")  .build()val response = client.newCall(request).execute()

PHP

• cURL

  <?php$curl = curl_init();curl_setopt_array($curl, [  CURLOPT_URL => "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only",  CURLOPT_RETURNTRANSFER => true,  CURLOPT_ENCODING => "",  CURLOPT_MAXREDIRS => 10,  CURLOPT_TIMEOUT => 30,  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  CURLOPT_CUSTOMREQUEST => "GET",  CURLOPT_HTTPHEADER => [    "Accept: application/json",    "Authorization: "  ],]);$response = curl_exec($curl);$err = curl_error($curl);curl_close($curl);if ($err) {  echo "cURL Error #:" . $err;} else {  echo $response;}
• Guzzle

  <?php$client = new GuzzleHttpClient();$response = $client->request('GET', 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only', [  'headers' => [    'Accept' => 'application/json',    'Authorization' => '',  ],]);echo $response->getBody();

PowerShell

• WebRequest

  $headers=@{}$headers.Add("Authorization", "")$headers.Add("Accept", "application/json")$response = Invoke-WebRequest -Uri 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only' -Method GET -Headers $headers
• RestMethod

  $headers=@{}$headers.Add("Authorization", "")$headers.Add("Accept", "application/json")$response = Invoke-RestMethod -Uri 'http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only' -Method GET -Headers $headers

R

library(httr)url <- "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only"response <- VERB("GET", url, add_headers('Authorization' = ''), content_type("application/json"), accept("application/json"))content(response, "text")

Ruby

require 'uri'require 'net/http'url = URI("http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only")http = Net::HTTP.new(url.host, url.port)request = Net::HTTP::Get.new(url)request["Authorization"] = ''request["Accept"] = 'application/json'response = http.request(request)puts response.read_body

Swift

import Foundationlet headers = [  "Authorization": "",  "Accept": "application/json"]let request = NSMutableURLRequest(url: NSURL(string: "http://api.sd-rtn.com/dev/v1/channel/user/appid/channelName/hosts_only")! as URL,                                        cachePolicy: .useProtocolCachePolicy,                                    timeoutInterval: 10.0)request.httpMethod = "GET"request.allHTTPHeaderFields = headerslet session = URLSession.sharedlet dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in  if (error != nil) {    print(error as Any)  } else {    let httpResponse = response as? HTTPURLResponse    print(httpResponse)  }})dataTask.resume()

For details about possible response status codes, see Response status codes.

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure.

If the status code is 200, the request succeeds, and the response body includes the following parameters:

Parameter	Type	Description
success	Boolean	The state of this request: true: Success. false: Reserved for future use.
data	Object	User information, including the following fields: channel_exist: Boolean. Whether the specified channel exists: true: The channel exists. false: The channel does not exist. Note: All other fields are not returned when the value of channel_exist is false. mode: Number. The channel profile: 1：The COMMUNICATION profile. 2: The LIVE_BROADCASTING profile. total: Number. The total number of the users in the channel. This field is returned only when mode is 1. users: Array. User IDs of all users in the channel. This field is returned only when mode is 1. broadcasters：Array. User IDs of all hosts in the channel. This field is returned only when mode is 2. audience: Array. User IDs of the first 10,000 audience members in the channel. This field is returned only when mode is 2 and the hosts_only parameter is not filled in. audience_total: Number. The total number of audience members in the channel. This field is returned only when mode is 2 and the hosts_only parameter is not filled in.

The following is a response example for a successful request:

In COMMUNICATION profile

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

In LIVE_BROADCASTING profile

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