Help Center/ SparkRTC/ API Reference/ Statistical Analysis/ Listing Users
Updated on 2022-10-08 GMT+08:00
View PDF
Share

Listing Users

Function

Lists users who joined a room within a specified period.

The maximum query time span is 90 days.

URI

GET /v1/{project_id}/rtc/users

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

app

Yes

String

Application ID.

room_id

No

String

Room ID.

uid

No

String

User ID.

nickname

No

String

Nickname of the user.

region

No

Array

Province where the user is located. The value can be the full name or abbreviation of a province, for example, Guangdong or GD.

isp

No

Array

ISP to which the user belongs.

state

No

Array

User status. The options are as follows:

  • FAIL: The user fails to join a room.

  • ONLINE: The user is in the room.

  • OFFLINE: The user has left the room.

start_time

No

String

Time when the query starts. UTC time in the format of YYYY-MM-DDThh:mm:ssZ, for example, 2020-04-23T06:00:00Z. If this parameter is not specified, data of the last hour is read by default.

end_time

No

String

Time when the query ends. UTC time in the format of YYYY-MM-DDThh:mm:ssZ, for example, 2020-04-23T06:00:00Z. If this parameter is not specified, the current time is used by default.

limit

No

Integer

Number of records in the query result.

offset

No

Integer

Query offset.

type

No

String

Query mode. The options are as follows:

  • detail: session level

  • summary: subscriber level (default)

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token. This parameter is mandatory when token authentication is used. The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Authorization

No

String

Authentication information. This parameter is mandatory when AK/SK-based authentication is used.

X-Sdk-Date

No

String

Time when the request is sent. This parameter is mandatory when AK/SK-based authentication is used.

X-Project-Id

No

String

Project ID, which is the same as that used in the URI. This parameter is mandatory when AK/SK-based authentication is used.

Response Parameters

Status code: 200

Table 4 Response header parameters

Parameter

Type

Description

X-Request-Id

String

Unique ID of the request.
Table 5 Response body parameters

Parameter

Type

Description

total

Integer

Total number of records.

limit

Integer

Number of records in the query result.

offset

Integer

Query offset.

users

Array of RtcUser objects

User list.
Table 6 RtcUser

Parameter

Type

Description

domain

String

Domain name.

app

String

Application identifier.

room_id

String

Room ID.

uid

String

User ID.

session

String

Session ID.

state

String

User Status

  • FAIL: The user fails to join a room.

  • ONLINE: The user is in the room.

  • OFFLINE: The user has left the room.

nick_name

String

Nickname of the user.

ip

String

User IP address.

region

String

Province where the user IP address is located.

isp

String

ISP to which the user IP address belongs.

device_model

String

User device model.

platform

String

User device platform.

sdk

String

User SDK version.

join_time

String

Time when the user joins a room. The format is YYYY-MM-DDThh:mm:ssZ.

leave_time

String

Time when the user leaves a room. The format is YYYY-MM-DDThh:mm:ssZ. If the user does not leave a room, a hyphen (-) is returned.

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Requests

GET /v1/{project_id}/rtc/users?app=5fa682b34a974f7ad24d223b

Example Responses

Status code: 200

This status code is returned if the request succeeds.

{
  "total" : "1,",
  "limit" : "10,",
  "offset" : 0,
  "users" : [ {
    "domain" : "603f71bdfa163e500aff1106c8bxxxxx.sparkrtc.myhuaweicloud.com",
    "app" : "603f71bdfa163e500aff1106c8xxxxx",
    "room_id" : "ac146d0f27799161917160702xxxxx",
    "uid" : "xxxxx",
    "session" : "0afa1af5a41a11eb802b7d4bc77xxxxx",
    "state" : "ONLINE",
    "nick_name" : "xxxxx",
    "ip" : "113.140.81.xx",
    "region" : "Shaanxi",
    "isp" : "CTCC",
    "device_model" : "iphone",
    "platform" : "web-Mac10_15_4",
    "sdk" : "1.4.0",
    "join_time" : "2021-04-23T09:55:32Z",
    "leave_time" : "-"
  } ]
}

Status code: 400

This status code is returned if the request fails.

{
  "error_code" : "DATA.100011001",
  "error_msg" : "Required String parameter 'app' is not present"
}

Status Codes

Status Code

Description

200

This status code is returned if the request succeeds.

400

This status code is returned if the request fails.

Error Codes

See Error Codes.

Parent topic: Statistical Analysis