Analytics REST API reference
Before working with the RESTful APIs, review the Agora Analytics features in Agora Console to gain a visual understanding of the quality and usage metrics that are available. For details, see the following user guides:
To use Agora Analytics RESTful APIs, subscribe to an Agora Analytics pricing plan.
Authentication
Before using the Agora RESTful API, you need to pass the basic HTTP authentication.
Data format
All requests are sent to the host: api.agora.io.
- Request: The request uses query string parameters in the URL.
- Response: The response content is in JSON format.
Call Inspector
With the Call Inspector RESTful APIs, you can search for calls with quality issues and obtain detailed metrics about call quality.
API limits
The limits of the Call Inspector RESTful APIs depend on the pricing plan you subscribe to.
The Starter, Standard, Premium, and Enterprise pricing plans have the following differences in terms of API limits:
- Request frequency is calculated using the server's UTC time.
- Data delay refers to the time required from the generation of data to the point where it can be queried.
- Endpoint is
/beta/analytics/call/lists:
| Starter | Standard | Premium | Enterprise | |
|---|---|---|---|---|
| Request frequency | N/A | No more than 1/second and 1,000/day | No more than 3/second and 2,000/day | No more than 10/second and 10,000/day |
| Available data | N/A | Within the past 1 day | Within the past 7 days | Within the past 15 days |
| Response content | N/A | A maximum of 8 hours of data | A maximum of 16 hours of data | A maximum of 24 hours of data |
| Data delay | N/A | 60 seconds | 20 seconds | 20 seconds |
- Endpoint is
/beta/analytics/call/sessionsor/beta/analytics/call/metrics:
| Starter | Standard | Premium | Enterprise | |
|---|---|---|---|---|
| Request frequency | N/A | No more than 1/second and 1,000/day | No more than 3/second and 2,000/day | No more than 10/second and 10,000/day |
| Available data | N/A | Within the past 1 day | Within the past 7 days | Within the past 15 days |
| Response content | N/A | A maximum of 1 hours of data | A maximum of 3 hours of data | A maximum of 6 hours of data |
| Data delay | N/A | 300 seconds | 150 seconds | 100 seconds |
Get call list
This method gets a list of the calls that meet the search criteria.
- Method:
GET - Endpoint:
/beta/analytics/call/lists
Query parameters
The following query string parameters are required in the URL as search criteria:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
start_ts | Number | The starting time of the search time frame. Unix time (in seconds since 1 January 1970) in UTC. |
end_ts | Number | The ending time of the search time frame. Unix time (in seconds since 1 January 1970) in UTC. |
cname | String | (Optional) The channel name. |
page_no | Number | (Optional) The page number. The default is 1. |
page_size | Number | (Optional) The number of calls on each page. The default is 20 and the maximum is 100. |
HTTP request example
Response example
Where:
code: Number. The status code.message: String. The error message.requestId: String. The unique identifier of the HTTP request corresponding to this HTTP response.total_size: Number. The total number of returned calls.page_no: Number. The page number.page_size: Number. The number of calls on each page.has_more: Boolean. Whether there are calls not included incall_lists.trueIndicates that some calls that meet the search criteria are not listed.falseIndicates that all calls that meet the query criteria are listed.
call_lists, try narrowing the search and resend the request.call_lists: JSONArray. The returned calls in descending order of the starting time. Each call has the following properties:call_id: String. The unique ID of the call.cname: String. The channel name.created_ts: Number. The starting time of the call. Unix time (in seconds since 1 January 1970) in UTC.destroyed_ts: Number. The ending time of the call. Unix time (in seconds since 1 January 1970) in UTC.finished: Boolean. Whether the call has finished or is still ongoing.call_pcu: Number. Peak number of callers.call_acu: Number. Average number of callers.call_audio_freeze_rate: Number. The audio freeze rate.call_video_freeze_rate: Number. The video freeze rate.
Get session details
This method gets the detailed call statistics of users by specifying the unique ID of the call.
- Method:
GET - Endpoint:
/beta/analytics/call/sessions
Query parameters
The following query string parameters are required in the URL to specify the call ID and statistics:
| Parameter | Type | Description |
|---|---|---|
start_ts | Number | The starting time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
end_ts | Number | The ending time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
call_id | String | The unique ID of the call. |
page_no | Number | (Optional) The page number. The default is 1. |
page_size | Number | (Optional) The number of user sessions on each page. The default is 20 and the maximum is 100. info To implement pagination, you need to specify a value for both page_no and page_size. |
uids | String | (Optional) The list of user IDs separated by commas. For example, uids=10001,10002,10003. You can specify a maximum of 10 user IDs. A user ID may occur twice in the list according to the actual scenario. Therefore, if you specify 10 user IDs in the request, 10 or more user IDs are returned. |
appid | String | App ID of your project. |
exclude_server_user | Boolean | (Optional) Whether or not to exclude Linux users. true by default, which represents excluding Linux users. |
HTTP request example
Response example
Where:
code: Number. The status code.message: String. The error message.requestId: String. The unique identifier of the HTTP request corresponding to this HTTP response.has_more: Boolean. Whether there are calls not included incall_lists.trueIndicates that some calls that meet the search criteria are not listed.falseIndicates that all calls that meet the query criteria are listed.
call_lists, try narrowing the search and resend the request.total_size: Number. The total number of returned user sessions.page_no: Number. The page number.page_size: Number. The number of user sessions on each page.call_info: JSONArray. Information of each user in the call in descending order of the joining time per page. Each user has the following properties:-
sid: String. The unique ID of the user session. -
cname: String. The channel name. -
uid: Number. The user ID. -
account: String. User-defined nickname. -
network: String. The network type. -
platform: String. The platform. -
speaker: Boolean. Whether or not the user speaks in the call. -
sdk_version: String. The SDK version. -
device_type: String. The type of the device used by the user. -
join_ts: Number. The time when the user joins the call. Unix time (in seconds since 1 January 1970) in UTC. -
leave_ts: Number. The time when the user leaves the call. Unix time (in seconds since 1 January 1970) in UTC. -
finished: Boolean. Whether the user is in the call or has left it. -
roles: String. The user role ID reflects the user's role and the functions used in this call.Audience: Receiving user.Host: The sending user.Screen Share: Screen sharing.Interative Live Streaming(ILS): Interactive live broadcast.Broadcast Streaming(BS): Live broadcast at high speed.Streaming robot: Streaming robot.On-Premise Recording: Local recording.Cloud Recording: Cloud recording.WebPage Recording: Page recording.
-
user_video_freeze_rate: Number. User-level video freeze rate. -
user_audio_freeze_rate: Number. User-level audio stuttering rate.
-
Get quality metrics
Gets the quality metrics of a specified call.
- Method:
GET - Endpoint:
/beta/analytics/call/metrics
Query parameters
The following query string parameters are required in the URL to specify the call:
| Parameter | Type | Description |
|---|---|---|
appid | String | App ID of your project. |
call_id | String | The unique ID of the call. |
start_ts | Number | The starting time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
end_ts | Number | The ending time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
sids | String | The list of user session IDs separated by commas, for example, sids=SXXXXXXXXXXXXXXXX1,SXXXXXXXXXXXXXXXX2. You can specify a maximum of 20 user session IDs. |
HTTP request example
Response example
code: Number. The status code.message: String. The error message.requestId: String. The unique identifier of the HTTP request corresponding to this HTTP response.metrics: JSONArray. Detailed quality metrics of each user session (sid). Each user session includes the following properties:sid: String. The unique ID of the user session.data: Array. The quality metrics of the user session.mid: Number. The ID of the metric. See Metrics ID for details.kvs: Array. Pairs of the timestamp and the corresponding metric value.peer_uid: Number. The user ID of the remote user. 0 represents that the returned metrics are the local user's.
Get call statistics
Retrieves statistics on the audio or video freeze rate for a specified call within a given time range and dimension.
- Method:
GET - Endpoint:
/beta/analytics/call/statistics
Query parameters
The following query string parameters are required in the URL to specify the call ID and statistics:
| Parameter | Type | Description |
|---|---|---|
appid | String | App ID of your project. |
call_id | String | The unique ID of the call. |
start_ts | Number | The starting time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
end_ts | Number | The ending time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
dimension | String | Statistical dimension; supports the following values:
|
metric | String | You can set the queried indicator to the following values:
|
HTTP request example
Response example
Where:
code: Number. The status code.message: String. The error message.requestId: String. The unique identifier of the HTTP request corresponding to this HTTP response.data: JSONArray. An array containing latitude, user count, and metric values:dimension_value: String. The value of the statistical dimension provided in the request.user_count: Number. The number of users.value: Number. The average metric value over the queried time range, matching the metric specified in the request.
Retrieve Audio/Video freeze rate statistics
This method gets audio or video freeze rate statistics for a specific call within a defined time range.
- Method:
GET - Endpoint:
/beta/analytics/call/freeze/bucket
Query parameters
The following query string parameters are required in the URL to specify the call ID and statistics:
| Parameter | Type | Description |
|---|---|---|
appid | String | App ID of your project. |
call_id | String | The unique ID of the call. |
start_ts | Number | The starting time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
end_ts | Number | The ending time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
metric | String | You can set the queried indicator to the following values:
|
HTTP request example
Response example
Where:
code: Number. The status code.message: String. The error message.requestId: String. The unique identifier of the HTTP request corresponding to this HTTP response.data: JSONArray. An array consisting of buckets and number of people:bucket: String. The call jam rate buckets represent the distribution of jam rates and include these values:[0%,3%)[3%,5%)[5%,10%)[10%,100%)
user_count: number. The number of people in this bucket.
Retrieve insight statistics
This method gets the insight statistics for a specific.
- Method:
GET - Endpoint:
/beta/analytics/call/statistics/time
Query parameters
The following query string parameters are required in the URL to specify the call ID and statistics:
| Parameter | Type | Description |
|---|---|---|
appid | String | App ID of your project. |
call_id | String | The unique ID of the call. |
start_ts | Number | The starting time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
end_ts | Number | The ending time of the call. Unix time (in seconds since 1 January 1970) in UTC. |
metric | String | The indicator can be set to one of the following values:
|
HTTP request example
Response example
Where:
code: Number. The status code.message: String. The error message.requestId: String. The unique identifier of the HTTP request corresponding to this HTTP response.data: JSONArray. An array containing timestamps and metric values:ts: Number. Timestamp in seconds.value: The indicator value at the current timestamp.
Data Insights
With the Data Insights RESTful APIs, you can query the usage and quality metrics within a specified time frame.
API limits
The limits of the Data Insights RESTful APIs depend on the pricing plan you subscribe to.
The Starter, Standard, Premium, and Enterprise pricing plans have the following differences in terms of API limits:
- Request frequency is calculated using the server's UTC time.
- Data delay refers to the time required from the generation of data to the point where it can be queried.
- Endpoint is
/beta/insight/usage/by_time:
| Starter | Standard | Premium | Enterprise | |
|---|---|---|---|---|
| Request frequency | N/A | N/A | No more than 3/minute and 40/day | No more than 10/minute and 60/day |
| Available data | N/A | N/A | Within the past 14 days | Within the past 30 days |
| Query time frame | N/A | N/A | No longer than 3 days | No longer than 7 days |
| Data granularity | N/A | N/A | Per day and hour | Per day and hour |
| Data delay | N/A | N/A | 12 hours | 6 hours |
- Endpoint is
/beta/insight/quality/by_time:
| Starter | Standard | Premium | Enterprise | |
|---|---|---|---|---|
| Request frequency | N/A | N/A | No more than 3/minute and 40/day | No more than 10/minute and 60/day |
| Available data | N/A | N/A | Within the past 14 days | Within the past 30 days |
| Query time frame | N/A | N/A | No longer than 3 days | No longer than 7 days |
| Data granularity | N/A | N/A | Per day, hour, and minute | Per day, hour, and minute |
| Data delay | N/A | N/A | 6 hours | 6 hours |
- Endpoint is
/beta/insight/usage/aggregation:
| Starter | Standard | Premium | Enterprise | |
|---|---|---|---|---|
| Request frequency | N/A | N/A | No more than 3/minute and 40/day | No more than 10/minute and 60/day |
| Available data | N/A | N/A | Within the past 14 days | Within the past 30 days |
| Data granularity | N/A | N/A | Per day and hour | Per day and hour |
| Data delay | N/A | N/A | 12 hours | 6 hours |
- Endpoint is
/beta/insight/quality/aggregation:
| Starter | Standard | Premium | Enterprise | |
|---|---|---|---|---|
| Request frequency | N/A | N/A | No more than 3/minute and 40/day | No more than 10/minute and 60/day |
| Available data | N/A | N/A | Within the past 14 days | Within the past 30 days |
| Data granularity | N/A | N/A | Per day and hour | Per day and hour |
| Data delay | N/A | N/A | 6 hours | 6 hours |
Query time-frame usage metrics
This method queries usage metrics for a specified time frame with granularity of hours or days, such as the number of users or channels.
- Method:
GET - Endpoint:
/beta/insight/usage/by_time
Query parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
startTs | Number | The start point (Unix timestamp) of the time frame to query. |
endTs | Number | The end point (Unix timestamp) of the time frame to query. |
metric | String | The metrics you want to query. You can set it to one of the following:userCount: The total number of users across all channels. A user joining the same channel with different user IDs or joining different channels with the same user ID is counted multiple times.sessionCount: The total count of users joining channels. Each time any user ID joins any channel is counted.channelCount: The total number of channels. A channel is counted once for each period between the time when the first user joins it and the time when the last user leaves it.peakCurrentChannels: The maximum number of channels in use.peakCurrentUsers: The maximum number of in-call users across channels.totalDuration: The total duration of video and audio-only calls calculated by the number of userstotalVideoDuration: The total duration of video calls calculated by the number of users.totalAudioDuration: The total duration of audio-only calls calculated by the number of users |
aggregateGranularity | String | The granularity of the returned data can be set to the following values:1d: By day. In this case, data for the entire day starting from UTC time 00:00 within the query time range is returned.1h: By hour. In this case, data with UTC time of whole hour within the query time range is returned. |
For more information about calculating by the number of users, see How does Agora calculate service minutes?
HTTP request example
The following example queries the total number of users across all channels starting from 8:00 am on July 1, 2021 to 8:00 am on July 3, 2021:
Response example
The response for the previous HTTP request example is as follows:
Response parameters
| Parameter | Type | Description |
|---|---|---|
code | Number | The status code. |
message | String | The success or error message. |
data | JSONArray | Each JSON object contains a Unix timestamp representing 12:00 am (UTC) on each day within the specified time frame and the corresponding value of the specified metrics. In the case of the previous request example, two JSON objects should be returned: One for 12:00 am on July 2, 2021, the other for 12:00 am on July 3, 2021.userCount: Number. The total number of users across all channels.ts: Number. Unix timestamp. |
Query time-series quality metrics
This method queries quality metrics for a specified time range with granularity of hours, days, or minutes, such as the audio or video freeze rate.
- Method:
GET - Endpoint:
/beta/insight/quality/by_time
Query parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
startTs | Number | The start point (Unix timestamp) of the time frame to query. |
endTs | Number | The end point (Unix timestamp) of the time frame to query. |
metric | String | The metrics you want to query. You can set it to one of the following:joinSuccessRate: The rate at which users attempting to join any channel succeed, which equals Number of users who have joined ÷ Number of attempts to join.joinSuccessIn5sRate: The rate at which users attempting to join any channel succeed within 5 seconds, which equals Number of users who have joined within 5 seconds ÷ Number of attempts to join.audioFreezeRate: The rate at which audio freezing occurs, which equals Total audio freeze time ÷ Total audio minutes calculated by the number of streams. Only audio freezes longer than 200 milliseconds are counted.videoFreezeRate: The rate at which video freezing occurs, which equals Total video freeze time ÷ Total video minutes calculated by the number of streams. Only video freezes longer than 600 milliseconds are counted.networkDelay: The rate at which network delay occurs, which equals Total end-to-end network delay ÷ Total audio and video minutes calculated by the number of streams. Only end-to-end network delays longer than 400 milliseconds are counted. |
aggregateGranularity | String | The granularity of the returned data can be set to the following values:1d: By day. In this case, data for the entire day starting from UTC time 00:00 within the query time range is returned.1h: By hour. In this case, data with UTC time of whole hour within the query time range is returned. |
productType | String | The product for which you want to query the metrics. You can set it to: Native: The Agora Video SDK for Android, iOS, macOS, and Windows.WebRTC: The Agora Video SDK for Web. |
For more information about calculating by the number of streams, see How does Agora calculate service minutes?
HTTP request example
The following example queries the hourly network delay rate starting from 8:00 am on July 1, 2021 to 8:00 am on July 2, 2021:
Response example
The response for the previous HTTP request example is as follows:
Response parameters
| Parameter | Type | Description |
|---|---|---|
code | Number | The status code. |
message | String | The success or error message. |
data | JSONArray | Each JSON object contains a Unix timestamp representing every hour within the specified time frame and the corresponding value of the specified metrics. In the case of the previous request example, 25 JSON objects should be returned. The first one is for 8:00 am on July 1, 2021, the second for 9:00 am on July 1, 2021, and so on. The last one is for 8:00 am on July 2, 2021. networkDelay: Number. The network delay rate.ts: Number. Unix timestamp. |
Query aggregated usage metrics
This method queries aggregated usage metrics for a specified time range and dimension, such as the number of users or channels.
- Method:
POST - Endpoint:
/beta/insight/usage/aggregation
Query parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
Body parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
startTs | Number | The start point (Unix timestamp) of the time frame to query. |
endTs | Number | The end point (Unix timestamp) of the time frame to query. |
metric | String | The metrics you want to query. You can set it to one of the following:userCount: The total number of users across all channels. A user joining the same channel with different user IDs or joining different channels with the same user ID is counted multiple times.sessionCount: The total count of users joining channels. Each time any user ID joins any channel is counted.channelCount: The total number of channels. A channel is counted once for each period between the time when the first user joins it and the time when the last user leaves it.peakCurrentChannels: The maximum number of channels in use.peakCurrentUsers: The maximum number of in-call users across channels.totalDuration: The total duration of video and audio-only calls calculated by the number of userstotalVideoDuration: The total duration of video calls calculated by the number of users.totalAudioDuration: The total duration of audio-only calls calculated by the number of users |
dimension | String | (Optional) The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed: country: Country. region: Region. net: Network type. sdk: SDK version. os: Operating system. device: Device model. device dimension) values in the corresponding dimension by default.info When the metric is set to peakConcurrentUsers or peakConcurrentChannels, specifying dimension and dimensionValues is not supported, and the request will only return aggregated results by App ID dimension. |
dimensionValues | String | (Optional) The values for the specified dimension. This parameter is only valid when the dimension parameter is set. All values must be enclosed in double quotes and separated by commas. If this parameter is set, the request will return the aggregated metric data corresponding to the values specified in dimensionValues. info You can obtain the top values for the current dimension by not specifying dimensionValues in the first request, and then select several values from the results based on your business needs to pass as the value of dimensionValues in subsequent requests. |
filters | JSONArray | (Optional) The region filters used to filter results by country. This parameter is only valid when dimension is set to region. It is used to filter results from the region dimension to include only results that belong to the specified country. The following properties are included: name: String. Only country is supported. value: String. The country to be filtered, and only one country value is supported. |
HTTP Request example
The following examples query the total number of users across all channels starting from 8:00 am on July 1, 2021 to 8:00 am on July 2, 2021:
Example 1: Query the top 20 countries with the highest number of calls and their respective call counts
Example 2: Query the number of calls for SDK versions 3.6.1.1 and 4.1.1
Example 3: Query the top 20 regions in China with the highest number of calls and their respective call counts ``
Response parameters
| Parameter | Type | Description |
|---|---|---|
code | Number | The status code. |
message | String | The success or error message. |
data | JSONArray | dimension field is not included in the request: Return the metric data for the App ID dimension.dimension field is included in the request: Return an array consisting of dimensions and metric data. |
Response example
Example 1: Query the top 20 countries with the highest number of calls and their respective call counts
Contains 20 sets of data, each representing the top 20 countries with the highest total number of calls between 8:00 am on July 1, 2021 and 8:00 am on July 2, 2021.
Example 2: Query the number of calls for SDK versions 3.6.1.1 and 4.1.1
Contains 2 sets of data, each representing the total number of calls between 8:00 am on July 1, 2021 and 8:00 am on July 2, 2021 for SDK versions 3.6.1.1 and 4.1.1 respectively.
Example 3: Query the top 20 regions in China with the highest number of calls and their respective call counts
Contains 20 sets of data, each representing the top 20 regions in China with the highest total number of calls between 8:00 am on July 1, 2021 and 8:00 am on July 2, 2021.
Query aggregated quality metrics
This method queries aggregated quality metrics for a specified time range and dimension, such as the audio or video freeze rate.
- Method:
POST - Endpoint:
/beta/insight/quality/aggregation
Query parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
Body parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
startTs | Number | The start point (Unix timestamp) of the time frame to query. |
endTs | Number | The end point (Unix timestamp) of the time frame to query. |
metric | String | The metrics you want to query. You can set it to one of the following:joinSuccessRate: The rate at which users attempting to join any channel succeed, which equals Number of users who have joined ÷ Number of attempts to join.joinSuccessIn5sRate: The rate at which users attempting to join any channel succeed within 5 seconds, which equals Number of users who have joined within 5 seconds ÷ Number of attempts to join.audioFreezeRate: The rate at which audio freezing occurs, which equals Total audio freeze time ÷ Total audio minutes calculated by the number of streams. Only audio freezes longer than 200 milliseconds are counted.videoFreezeRate: The rate at which video freezing occurs, which equals Total video freeze time ÷ Total video minutes calculated by the number of streams. Only video freezes longer than 600 milliseconds are counted.networkDelay: The rate at which network delay occurs, which equals Total end-to-end network delay ÷ Total audio and video minutes calculated by the number of streams. Only end-to-end network delays longer than 400 milliseconds are counted. |
dimension | String | (Optional) The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed: country: Country. region: Region. net: Network type. sdk: SDK version. os: Operating system. device: Device model. channelSize: Size of the channel. device dimension) values in the corresponding dimension by default.info When the metric is set to peakConcurrentUsers or peakConcurrentChannels, specifying dimension and dimensionValues is not supported, and the request will only return aggregated results by App ID dimension. |
dimensionValues | String | (Optional) The values for the specified dimension. This parameter is only valid when the dimension parameter is set. All values must be enclosed in double quotes and separated by commas. If this parameter is set, the request will return the aggregated metric data corresponding to the values specified in dimensionValues. info You can obtain the top values for the current dimension by not specifying dimensionValues in the first request, and then select several values from the results based on your business needs to pass as the value of dimensionValues in subsequent requests. info When dimension is channelSize, dimensionValues is not supported. The results will be grouped based on the preset gradient scale. |
filters | JSONArray | (Optional) The region filters used to filter results by country. This parameter is only valid when dimension is set to region. It is used to filter results from the region dimension to include only results that belong to the specified country. The following properties are included: name: String. Only country is supported. value: String. The country to be filtered, and only one country value is supported. |
HTTP Request example
The following examples query the audio freeze rate across all channels starting from 8:00 am on July 1, 2021 to 8:00 am on July 2, 2021:
Example 1: Query the top 20 countries with the highest audio freeze rates and their respective audio freeze rate
Example 2: Query the audio freeze rates for SDK versions 3.6.1.1 and 4.1.1
Example 3: Query the top 20 regions in China with the highest audio freeze rates and their respective audio freeze rate
Response parameters
| Parameter | Type | Description |
|---|---|---|
code | Number | The status code. |
message | String | The success or error message. |
data | JSONArray |
|
Response example
Example 1: Query the top 20 countries with the highest audio freeze rates and their respective audio freeze rate
Contains 20 sets of data, each representing the top 20 countries with the highest audio freeze rates between 8:00 am on July 1, 2021 and 8:00 am on July 2, 2021.
Example 2: Query the audio freeze rates for SDK versions 3.6.1.1 and 4.1.1
Contains 2 sets of data, each representing the audio freeze rates between 8:00 am on July 1, 2021 and 8:00 am on July 2, 2021 for SDK versions 3.6.1.1 and 4.1.1 respectively.
Example 3: Query the top 20 regions in China with the highest audio freeze rates and their respective audio freeze rate
Contains 20 sets of data, each representing the top 20 regions in China with the highest audio freeze rates between 8:00 am on July 1, 2021 and 8:00 am on July 2, 2021.
Real-time Monitoring
With the Real-time Monitoring RESTful APIs, you can query the scale and quality metrics within a specified time frame. The granularity of the returned data is seconds, which can reflect the actual situation in close to real time.
The data is returned in regular 20-second time windows starting from 00:00:00. For example, [00:00:00, 00:00:20] is a time window, while [00:00:10, 00:00:30] is not a time window.
API limits
The limits of the Real-time Monitoring RESTful APIs depend on the pricing plan you subscribe to.
The Starter, Standard, Premium, and Enterprise pricing plans have the following differences in terms of API limits:
| Starter | Standard | Premium | Enterprise | |
|---|---|---|---|---|
| Request frequency | N/A | N/A | No more than 3/minute and 480/day | No more than 10/minute and 1440/day |
| Available data | N/A | N/A | Within the past 40 minutes | Within the past 60 minutes |
| Query time frame | N/A | N/A | No longer than 40 minutes | No longer than 60 minutes |
| Data delay | N/A | N/A | 40 seconds | 20 seconds |
Request frequency is calculated using the server's UTC time.
Query real-time scale metrics
This method queries the real-time number of users and channels.
- Method:
GET - Endpoint:
/beta/realtime/usage/by_time_20sec
Query parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
startTs | Number | The start point (Unix timestamp) of the time frame to query. The time window that startTs falls in is included in the response. |
endTs | Number | The end point (Unix timestamp) of the time frame to query. The time window that endTs falls in is not included in the response. |
productType | String | The product for which you want to query the metrics. You can set it to:Native: The Agora Video SDK for Android, iOS, macOS, and Windows.WebRTC: The Agora Video SDK for Web. |
metric | String | The metric you want to query. You can set it to one of the following options:userCount: The total number of users across all in-use channels. A user joining multiple channels is counted multiple times.channelCount: The total number of channels. A channel is counted once for each period between the time when the first user joins it and the time when the last user leaves it. |
dimension | String | (Optional) The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed: country: Country. region: Region. net: Network type. sdk: SDK version. os: Operating system. device: Device model. info You can obtain the top values for the current dimension by querying top 20 real-time scale metrics, and then select several values from the results based on your business needs to pass as the value of dimensionValues in subsequent requests. |
dimensionValues | String | (Optional) The values for the specified dimension. This parameter is only valid when the dimension parameter is set. All values must be enclosed in double quotes and separated by commas. If this parameter is set, the request will return the aggregated metric data corresponding to the values specified in dimensionValues. |
cname | String | (Optional)The channel name. If you do not specify this parameter, the metric data of your entire project (rather than a specific channel) is returned. |
HTTP request example
The following example queries the real-time number of users for SDK versions 3.6.1.1 and 4.1.1, with startTs set to 08:10:10 on September 17, 2021 and endTs set to 08:11:10 on the same day. The HTTP request is as follows:
Response parameters
The response contains the following fields:
| Field | Type | Description |
|---|---|---|
code | Number | The status code. 200 indicates that the request is successful. |
message | String | The error message. |
data | JSONArray | An array consisting of the following fields:metric field specified in the request.ts: The Unix timestamp of the start point of the corresponding time window. |
Response example
For the previous HTTP request example, the response includes the total number of users, corresponding SDK version, and Unix timestamp of the following time windows:
- [00:10:00, 00:10:20] on September 17, 2021
- [00:10:20, 00:10:40] on September 17, 2021
- [00:10:40, 00:11:00] on September 17, 2021
Query real-time quality metrics
This method queries the real-time values of quality metrics such as the audio or video freeze rate.
- Method:
GET - Endpoint:
/beta/realtime/quality/by_time_20sec
Query parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
startTs | Number | The start point (Unix timestamp) of the time frame to query. The time window that startTs falls in is included in the response. |
endTs | Number | The end point (Unix timestamp) of the time frame to query. The time window that endTs falls in is not included in the response. |
productType | String | The product for which you want to query the metrics. You can set it to one of the following options:Native: The Agora Video SDK for Android, iOS, macOS, and Windows.WebRTC: The Agora Video SDK for Web. |
metric | String | The metrics you want to query. You can set it to one of the following options:joinSuccessRate: The rate at which users attempting to join any channel succeed, which equals Number of users who have joined ÷ Number of attempts to join.joinSuccessIn5sRate: The rate at which users attempting to join any channel succeed within 5 seconds, which equals Number of users who have joined within 5 seconds ÷ Number of attempts to join.audioFreezeRate: The rate at which audio freezing occurs, which equals Total audio freeze time ÷ Total audio minutes calculated by the number of streams. Only audio freezes longer than 200 milliseconds are counted.videoFreezeRate: The rate at which video freezing occurs, which equals Total video freeze time ÷ Total video minutes calculated by the number of streams. Only video freezes longer than 600 milliseconds are counted.networkDelay: The rate at which network delay occurs, which equals Total end-to-end network delay ÷ Total audio and video minutes calculated by the number of streams. Only end-to-end network delays longer than 400 milliseconds are counted. |
dimension | String | (Optional) The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed: country: Country. region: Region. net: Network type. sdk: SDK version. os: Operating system. device: Device model. info You can obtain the top values for the current dimension by querying top 20 real-time scale metics, and then select several values from the results based on your business needs to pass as the value of dimensionValues in subsequent requests. |
dimensionValues | String | (Optional) The values for the specified dimension. This parameter is only valid when the dimension parameter is set. All values must be enclosed in double quotes and separated by commas. If this parameter is set, the request will return the aggregated metric data corresponding to the values specified in dimensionValues. |
cname | String | (Optional) The channel name. If you do not specify this parameter, the metric data of your entire project (rather than a specific channel) is returned. |
uids | String | (Optional) The list of user IDs (uid). You need to separate multiple user IDs with commas (for example, uids=10001,10002,10003). You can specify a maximum of 10 user IDs. The uids parameter takes effect only when you specify the cname parameter. |
HTTP request example
The following example queries the network delay rate from 00:10:10 to 00:11:10 on September 17, 2021:
Example 1: uids is not specified
Example 2: uids is specified as 2303692334 and 2963430861
Example 3: dimension is specified as sdkVersion, and dimensionValues as 3.6.1.1 and 4.1.1
Response parameters
The response contains the following fields:
| Field | Type | Description |
|---|---|---|
code | Number | The status code. 200 indicates that the request is successful. |
message | String | The error message. |
data | JSONArray | uids field: An array of metric data and Unix timestamps (in seconds).uids field: An array of uid, metric data, and Unix timestamps (in seconds).dimension and dimensionValues fields: Arrays of metric data, dimensions, and Unix timestamps (in seconds). |
Response example
For the previous HTTP request example, the response includes data of the following time windows:
- [00:10:00, 00:10:20] on September 17, 2021
- [00:10:20, 00:10:40] on September 17, 2021
- [00:10:40, 00:11:00] on September 17, 2021
Example 1: uids is not specified
Example 2: uids is specified as 2303692334 and 2963430861
Example 3: dimension is specified as sdkVersion, and dimensionValues as 3.6.1.1 and 4.1.1
Query top 20 real-time scale metrics
This method queries the top 20 grouped data of real-time scale for a specified dimension and provides content input for the dimensionValues parameter in Query real-time scale.
- Method:
GET - Endpoint:
/beta/realtime/usage/dimension/top20
Query parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
ts | Number | The start point (Unix timestamp) of the time frame to query. The actual query range is [ts, ts + 20s]. |
productType | String | The product for which you want to query the metrics. You can set it to:Native: The Agora Video SDK for Android, iOS, macOS, and Windows.WebRTC: The Agora Video SDK for Web. |
metric | String | The metric you want to query. You can only set it userCount, namely the number of users. One user ID in one channel is counted as one user, while one user ID in multiple channels is counted as multiple users. |
dimension | String | The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed: country: Country. region: Region. net: Network type. sdk: SDK version. os: Operating system. device: Device model. device dimension) values in the corresponding dimension by default. |
Request example
The following example queries the top 20 number of users for each SDK version starting from 08:10:10 on September 17, 2021 is as follows:
Response parameters
The response contains the following fields:
| Field | Type | Description |
|---|---|---|
code | Number | The status code. 200 indicates that the request is successful. |
message | String | The error message. |
data | JSONArray | An array consists of dimensions, metric, and the starting and ending Unix timestamps (in seconds) of the time window. |
Response example
The response contains 20 sets of data, each representing the top 20 call volume data for each SDK version during the time window from 08:10:10 to 08:10:30 on September 17, 2021.
Query top 20 real-time quality metrics
This method queries the top 20 grouped data of real-time call quality for a specified dimension and provides content input for the dimensionValues parameter in Query real-time quality.
- Method:
GET - Endpoint:
/beta/realtime/quality/dimension/top20
Query parameters
The following query string parameters are required in the URL:
| Parameter | Type | Description |
|---|---|---|
appid | String | The App ID of your project. |
ts | Number | The start point (Unix timestamp) of the time frame to query. The actual query range is [ts, ts + 20s]. |
productType | String | The product for which you want to query the metrics. You can set it to:Native: The Agora Video SDK for Android, iOS, macOS, and Windows.WebRTC: The Agora Video SDK for Web. |
metric | String | The metrics you want to query. You can set it to one of the following options:joinSuccessRate: The rate at which users attempting to join any channel succeed, which equals Number of users who have joined ÷ Number of attempts to join.joinSuccessIn5sRate: The rate at which users attempting to join any channel succeed within 5 seconds, which equals Number of users who have joined within 5 seconds ÷ Number of attempts to join.audioFreezeRate: The rate at which audio freezing occurs, which equals Total audio freeze time ÷ Total audio minutes calculated by the number of streams. Only audio freezes longer than 200 milliseconds are counted.videoFreezeRate: The rate at which video freezing occurs, which equals Total video freeze time ÷ Total video minutes calculated by the number of streams. Only video freezes longer than 600 milliseconds are counted.networkDelay: The rate at which network delay occurs, which equals Total end-to-end network delay ÷ Total audio and video minutes calculated by the number of streams. Only end-to-end network delays longer than 400 milliseconds are counted. |
dimension | String | The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed: country: Country. region: Region. net: Network type. sdk: SDK version. os: Operating system. device: Device model. device dimension) values in the corresponding dimension by default. |
extraMetrics | String | Additional indicator, used to help determine the validity of data. Only supports setting to userCount, that is, the number of users under the current dimension. |
Request example
The following example passes in extraMetrics and queries the top 50 audio freeze rate values for each device starting from 20:00:00 on December 21, 2022:
Response parameters
The response contains the following fields:
| Field | Type | Description |
|---|---|---|
code | Number | The status code. 200 indicates that the request is successful. |
message | String | The error message. |
data | JSONArray | An array consists of dimensions, metric, and the starting and ending Unix timestamps (in seconds) of the time window. |
Response example
The response contains 50 sets of data, each representing the top 50 audio freeze rate values for each device model during the time window from 20:00:00 to 20:00:20 on December 21, 2022.
References
Status codes
| Code | Description |
|---|---|
200 | The request is successful. |
300 | The API limits are exceeded (Call Search only) |
400 | Invalid parameters. |
401 | Unauthorized. |
403 | Wrong authorization information. The request is forbidden. |
404 | Wrong API invoked. |
500 | Unknown error. |
When 300 is returned, you might get the following error messages:
| Error message | Description | Examples of error fix |
|---|---|---|
qps limit error | The limit on requests per second is exceeded. | If qps limit = 10, ensure that current qps < 10 |
qpd limit error | The limit on requests per day is exceeded. | If qpd limit = 10000, ensure that current qpd < 10000 |
query latency limit error | The limit on data delay is exceeded. | If query latency limit = 10s and current time = 1623316864, ensure that end_ts < 1623316864 - 10 |
query time range limit error | The limit on available calls is exceeded. | If query time range limit = 3d and current time = 1623316864, ensure that start_ts > 1623316864 - 3 * 86400(s) |
query time length limit error | The limit on response content is exceeded. | If query time length limit = 3h, ensure that end_ts -start_ts < 3 * 3600(s) |
you have no auth to access this service, please buy or upgrade your service package | You have no access to this service. | N/A |
Metrics ID
mid | Description | Unit | Example |
|---|---|---|---|
| 20001 | App CPU usage. | % | 27% |
| 20002 | System CPU usage. | % | 15% |
| 20003 | The upstream bitrate of the audio. | Kbps | 126 Kbps |
| 20004 | The downstream bitrate of the audio. | Kbps | 108 Kbps |
| 20005 | The freeze time in rendering the audio. | ms | 106.67 ms |
| 20006 | The upstream bitrate of the low-quality video stream. | Kbps | 472 Kbps |
| 20007 | The capturing frame rate of the video. | fps | 16 fps |
| 20008 | The upstream frame rate of the high-quality video stream. | fps | 12 fps |
| 20009 | The downstream bitrate of the high-quality video. | Kbps | 309 Kbps |
| 20010 | The downstream frame rate of the high-quality video. | fps | 6 fps |
| 20011 | The freeze time in rendering the video. | ms | 2000.50 ms |
| 20015 | The upstream packet loss rate of the audio. | % | 1% |
| 20016 | The end-to-end packet loss rate of the audio. | % | 3% |
| 20017 | The upstream packet loss rate of the video. | % | 5% |
| 20018 | The end-to-end packet loss rate of the video. | % | 7% |
| 20019 | The width of the received video. | —— | 360 |
| 20020 | The height of the received video. | —— | 640 |
| 20021 | The task scheduling delay. | ms | 2 ms |
| 20022 | The round-trip time delay from the client to the local router. | ms | 3 ms |
| 20023 | The upstream frame rate of the low-quality video stream. | fps | 108 fps |
| 20024 | The upstream bitrate of the video stream. | Kbps | 126 Kbps |
| 20025 | The sampling volume of the sent audio. | dB | 105 dB |
| 20026 | The playback volume of the received audio. | dB | 98 dB |
| 20027 | The width of the sent video. | —— | 360 |
| 20028 | The height of the sent video. | —— | 640 |
| 20030 | The downstream bitrate of the low-quality video stream. | Kbps | 100 Kbps |
| 20031 | The downstream frame rate of the low-quality video stream. | fps | 6 fps |
| 20032 | The width of the received low-quality video. | —— | 360 |
| 20033 | The height of the received low-quality video. | —— | 640 |
| 20034 | The width of the sent low-quality video. | —— | 360 |
| 20035 | The height of the sent low-quality video. | —— | 640 |
| 20036 | The WebRTC downstream packet loss rate of the video. | ||
| 20037 | The WebRTC upstream packet loss rate of the audio. | ||
| 20038 | The WebRTC upstream packet loss rate of the video. |