Skip to main content

Query host list

This method gets the list of hosts in the specified channel in the live broadcast scenario.

Prototype

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

This API is only used in the live broadcast profile (mode is set to 2). Users in the same channel must use the same profile. Otherwise, the query results may be inaccurate.

This API and the query user status API can both be used to synchronize the online status of hosts. Compared to the query user status API, this API requires a lower call frequency and has a higher efficiency. Therefore, Agora recommends using this API for this purpose.

Request parameters

Path parameters

Pass the following path parameters in the request URL:

ParameterTypeRequired/OptionalDescription
appidStringRequiredThe 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.
  • channelNameStringRequiredThe channel name.

    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.

    Request examples

    Sample request:

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

    Response parameters

    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:

    ParameterTypeDescription
    successBooleanThe state of this request:
  • true: Success.
  • false: Reserved for future use.
  • dataObjectUser 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.
    • broadcasters:Array. User IDs of all hosts in the channel. This field is returned only when mode is 2.

    Response example

    The following is a response example for a successful request:


    _11
    {
    _11
    "success": true,
    _11
    "data": {
    _11
    "channel_exist": true,
    _11
    "mode": 2,
    _11
    "broadcasters": [
    _11
    574332,
    _11
    1347839
    _11
    ]
    _11
    }
    _11
    }

    Interactive Live Streaming