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

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

Retrieves channels under a specified project.

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

## Servers

- https://api.agora.io

Use this endpoint to get the list of all channels under a specified project. The channel list is returned by page; specify the page number and page size in the request URL.


:::warning[Important]
The Agora RESTful API supports only HTTPS with TLS 1.0, 1.1, or 1.2. Requests over plain HTTP are not supported.
:::

:::info[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 on different pages.
- A channel does not appear on any page.
:::

## 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.
- `page_no` (query, optional, number) - The page number to query. The default value is `0`, which is the first page. The value of `page_no` cannot exceed `(total number of channels / page_size) - 1`; otherwise, the specified page contains no channels.
  - Default: `0`
- `page_size` (query, optional, number) - The number of channels per page. The value range is [1,500].
  - Default: `100`
  - Range: `[1, 500]`

### 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/<appid>?page_no=0&page_size=100' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <your_base64_encoded_credentials>'
```

### Node.js

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

const options = {
  method: 'GET',
  hostname: 'api.sd-rtn.com',
  port: null,
  path: '/dev/v1/channel/<appid>?page_no=0&page_size=100',
  headers: {
    Authorization: 'Basic <your_base64_encoded_credentials>',
    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();
```

### Python

```python
import http.client

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

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

conn.request("GET", "/dev/v1/channel/<appid>?page_no=0&page_size=100", 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) - Channel statistics.
  - `data.channels` (array) - The list of channels. If the specified page contains no channels, this field is empty.

The list of channels. Each object in the array represents one channel and contains the following fields. If the specified page contains no channels, this field is empty.
    - `data.channels.items` (object)
      - `data.channels.items.channel_name` (string) - The channel name.
      - `data.channels.items.user_count` (number) - The total number of users in the channel.
  - `data.total_size` (number) - The total number of channels under the specified project.
### default

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

No schema.

## Response examples

### 200

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