# Get the banning rule list (/en/api-reference/api-ref/rtc/get-ban-rule-list)

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

Retrieves all banning rules.

- OpenAPI: /openapi/rtc/channel-management.en.yaml
- Operation ID: cma-get-ban-rule-list
- Method: GET
- Path: /dev/v1/kicking-rule
- Endpoint: https://api.agora.io/dev/v1/kicking-rule

## Servers

- https://api.agora.io

Use this endpoint to get the list of all banning rules.


## Authorization

This endpoint requires authentication.

- `basicAuth`

## Parameters

- `appid` (query, 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.

### 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/kicking-rule?appid=4855xxxxxxxxxxxxxxxxxxxxxxxxeae2' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <your_base64_encoded_credentials>'
```

### Node.js

```javascript
const https = require('https');
const options = {
  method: 'GET',
  hostname: 'api.sd-rtn.com',
  port: null,
  path: '/dev/v1/kicking-rule?appid=4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',
  headers: {
    Authorization: 'Basic <your_base64_encoded_credentials>',
    Accept: 'application/json'
  }
};

const req = https.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.HTTPSConnection("api.sd-rtn.com")

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

conn.request("GET", "/dev/v1/kicking-rule?appid=4855xxxxxxxxxxxxxxxxxxxxxxxxeae2", 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.

- `status` (string) - The status of this request. `success` means the request succeeds.
- `rules` (array) - The list of banning rules. Each object in the array represents one banning rule.
  - `rules.items` (object)
    - `rules.items.id` (number) - The rule ID. Required to update or delete the rule.
    - `rules.items.appid` (string) - The App ID of the project.
    - `rules.items.uid` (number) - The user ID.
    - `rules.items.opid` (number) - The operation ID, which can be used to track operation records when troubleshooting.
    - `rules.items.cname` (string) - The channel name.
    - `rules.items.ip` (string) - The IP address of the user.
    - `rules.items.ts` (string) - The UTC time when this rule expires.
    - `rules.items.privileges` (array) - The banned user privileges. Possible values: `join_channel`, `publish_audio`, `publish_video`.
      - `rules.items.privileges.items` (string)
        - Allowed: `join_channel` | `publish_audio` | `publish_video`
    - `rules.items.createAt` (string) - The UTC time when this rule was created.
    - `rules.items.updateAt` (string) - The UTC time when this rule was last updated.
### default

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

No schema.

### Reference

### Best practices for rule management

To maximize the success rate of create, update, and delete operations, query requests are assigned a lower priority. Under poor network conditions, the success rate and accuracy of GET requests may degrade and some request records may be missing from the results.

When you call POST to create a rule where `time` is not set to `0`, use the following best practices to update or delete it later:

- Save the rule ID returned in the POST request on your server, and rely on this ID for subsequent update and delete operations.
- To ensure that you can still obtain the rule ID under poor network conditions, set the timeout for the POST request to 20 seconds or higher. Make sure that the timeout is set to no less than 5 seconds.
- In case the POST request times out or returns a `504` error, use the response of the GET method to obtain the rule ID. If the rule exists, it indicates that the POST request was successful, and you can save the rule ID on your server.


## Response examples

### 200

```json
{
  "status": "success",
  "rules": [
    {
      "id": 1953,
      "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
      "uid": 589517928,
      "opid": 1406,
      "cname": "11",
      "ip": "192.168.0.1",
      "ts": {},
      "privileges": [
        "join_channel"
      ],
      "createAt": {},
      "updateAt": {}
    }
  ]
}
```