Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

Query channel list

This method gets the list of all channels under a specified project.

Prototype

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

This API gets the channel list by page. In the request URL, you can specify the page number and the number of channels shown on the page. A successful request returns the channel list of the specified page according to the set page_size.

Note
If the number of users in a channel changes frequently, the query results may be inaccurate. The following situations may occur:
  • A channel appears repeatedly in different pages.
  • A channel does not appear in any page.

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.
  • Query parameters

    Pass the following query parameters in the request URL:

    ParameterTypeRequired/OptionalDescription
    page_noNumberOptionalThe page number that you want to query. The default value is 0, that is, the first page.

    Note: The value of page_no cannot exceed (the total number of channels/the value of page_size - 1); otherwise, the specified page does not contain any channel.

    page_sizeNumberOptionalThe number of channels on a page. The value range is [1,500], and the default value is 100.

    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

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

    Sample request:

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

    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.
  • dataObjectChannel statistics, including the following fields:
    • channels: Array. The list of channels. This array contains multiple objects. Each object shows the information on a channel and includes the following fields:
      • channel_name: String. The channel name.
      • user_count: Number. The total number of users in the channel.
      Note: If the specified page does not contain any channel, this field is empty.
    • total_size: Number. The total number of channels under the specified project.

    Response example

    The following is a response example for a successful request:

    {  "success": true,  "data": {    "channels": [      {        "channel_name": "lkj144",        "user_count": 3      }    ],    "total_size": 1  }}

    Video Calling