Documentation
Server APIs v2
Room signaling
Get a room's user list

Get a room's user list

Last updated：2024-08-09 17:20

1 Description

Get the list of users in a room.

2 Request method and endpoint

Request method: GET
Request endpoint: https://rtc-api.zego.im/?Action=DescribeUserList
Transmission protocol: HTTPS
Rate limit:
- Same AppID: 200 times/second
- Same room: 1 times/1 seconds

3 Request parameters

Listed below are the parameters specific to this request and part of the public request parameters. For the complete list of public request parameters, see Server APIs public request parameters.

Parameter	Type	Required	Description
RoomId	String	Yes	Room ID. If the room does not exist, an empty list will be returned.
Mode	Int32	No	The default value for sorting the login time of users in a room is 0. 0: in positive chronological order 1: in reverse chronological order
Limit	Int32	No	The number of users returned in a single request, ranging from 0 to 200. This means that a maximum of 200 users can be returned in one call to this interface. The default value is 200. If the number of users in the room exceeds 200, you need to use the Marker value (user starting position identifier) from the previous call to this interface to make another call and query the remaining users. For example, if there are 450 users in the room and you call this interface to query the user list: On the first call to this interface, set the input parameter Marker to empty and query users 1 to 200; the returned result will have a Marker value, let's assume it is "marker1". On the second call to this interface, set the input parameter Marker to "marker1" and query users 201 to 400; the returned result will have a Marker value, let's assume it is "marker2". On the third call to this interface, set the input parameter Marker to "marker2" and query users 401 to 450; the query is completed and the returned result will have an empty Marker value.
Marker	String	No	Query the user start bit identifier, the response of each request is returned, if it is empty, the user information will be returned from the beginning.

4 Request Example

https://rtc-api.zego.im/?Action=DescribeUserList
&RoomId=room_demo
&Mode=0
&Limit=2
&Marker=
&<public Request Parameters>

5 Response parameters

Parameter	Type	Description
Code	Int32	Return code.
Message	String	A Description of the operation result.
RequestId	String	Request ID.
Data	Object	Response data.
Marker	String	User start bit identifier.
UserList	Array of Object	User list.
UserId	String	Username.
UserName	String	User nickname.
UserRole	UInt32	User role. 1: Anchor. 2: Viewer. 4: Administrator. This type of user mainly exists in scenarios such as cloud recording and audio/video stream auditing. The user-related interfaces of the client SDK will filter out this type of user. This return parameter only has practical significance when accessing the LiveRoom service. Please ignore this parameter when accessing the Express service.

6 Response example

{
    "Code": 0,
    "Message": "success",
    "RequestId": "TestRequestId1635940600561291000",
    "Data": {
        "Marker": "1635940599950-user2",
        "UserList": [
            {
                "UserId": "user1",
                "UserName": "user1"
                "UserRole": 1
            },
            {
                "UserId": "user2",
                "UserName": "user2"
                "UserRole": 2
            }
        ]
    }
}

7 Return codes

Please refer to Return codes.