# Get channel events (/en/api-reference/api-ref/signaling/channel-events)

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

Retrieves Signaling channel join and leave events.

- OpenAPI: /openapi/rtm/signaling-rest.en.yaml
- Operation ID: get-channel-events
- Method: GET
- Path: /{appid}/rtm/vendor/channel_events
- Endpoint: https://api.agora.io/dev/v2/project/{appid}/rtm/vendor/channel_events

## Servers

- https://api.agora.io/dev/v2/project

This method retrieves channel events from the Agora Signaling server. Events you acquire using this API are removed from the server and cannot be retrieved again.

The Signaling server stores a maximum of 2,000 events, with the latest event replacing the oldest when this limit is exceeded. The backend returns a maximum of 1,000 events per request, and the number of requests for each app ID must not exceed 10 per second.


:::info[Note]
Events acquired using this API are removed from the server and cannot be retrieved again. The Signaling server stores a maximum of 2,000 events, replaces the oldest event when this limit is exceeded, returns at most 1,000 events per request, and allows up to 10 requests per second for each App ID.
:::

:::warning[Caution]
Agora does not guarantee event time sequence across geographical regions. Events pulled from different regions may contain duplicates since synchronization only occurs within regions, not across them.
:::

## Authorization

This endpoint requires authentication.

- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of your Agora project.

### Request

This endpoint does not require any query parameters or a request body.


## Request body

No request body.

## Request examples

### curl

```bash
curl -X GET 'https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/vendor/channel_events' \
     -H 'Authorization: Basic <your_base64_encoded_credentials>'
```

### Python

```python
import requests

   url = 'https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/vendor/channel_events'

   headers = {
     'Authorization': 'Basic <your_base64_encoded_credentials>'
   }

   try:
     response = requests.get(url, headers=headers)
     print("Status:", response.status_code)
     print("Response:", response.json())
   except Exception as error:
     print("Error:", error)
```

### Node.js

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

   const url = 'https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/vendor/channel_events';

   const headers = {
     'Authorization': 'Basic <your_base64_encoded_credentials>'
   };

   axios.get(url, { headers })
   .then(response => {
     console.log("Status:", response.status);
     console.log("Response:", response.data);
   })
   .catch(error => {
     console.error("Error:", error.response ? error.response.data : error.message);
   });
```


### Response

- If the returned status code is `200`, the request was successful. The response body contains the result of the request.
- If the returned status code is not `200`, the request failed. The response body includes the error code and description. Refer to [status codes](/en/realtime-media/rtm/reference/error-codes#restful-api-error-codes) to understand the possible reasons for failure.


## Responses

### 200

The request was successful. The response body contains the result of the request.

- `result` (string) - The result of this request. `success` if it succeeds, `failed` if it fails.
- `request_id` (string) - The unique ID of this request.
- `events` (array) - An array of join and leave events.
  - `events.items` (object)
    - `events.items.group_id` (string) - The corresponding channel ID.
    - `events.items.user_id` (string) - The corresponding user ID.
    - `events.items.type` (string) - Event type: `Join` when a user has joined the channel, `Leave` when a user has left the channel.

The event type:

 - Join: A user has joined the channel.
 - Leave: A user has left the channel.
    - `events.items.ms` (integer) - Number of milliseconds since January 1, 1970 (UTC) to the UTC time when the server receives the message.
### default

The request failed. The response body includes the error code and description.

No schema.

## Response examples

### 200

```json
{
  "result": "success",
  "request_id": "10116762670167749259",
  "events": [
    {
      "group_id": "example_channel_id",
      "user_id": "rtmtest_RTM_4852_4857w7%",
      "type": "Join",
      "ms": 1578027418981
    }
  ]
}
```