# Analytics REST API reference (/en/api-reference/api-ref/agora-analytics/analytics-rest-api)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
Before working with the RESTful APIs, review the Agora Analytics features in [Agora Console](https://console.agora.io/v2) to gain a visual understanding of the quality and usage metrics that are available. For details, see the following user guides:
* [Call Inspector](#call-inspector)
* [Data Insights](#data-insights)
* [Real-time Monitoring](#real-time-monitoring)
To use Agora Analytics RESTful APIs, subscribe to an [Agora Analytics pricing plan](/en/realtime-media/agora-analytics/reference/pricing).
## Authentication [#authentication]
Before using the Agora RESTful API, you need to pass the [basic HTTP authentication](analytics-restful-authentication).
## Data format [#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 [#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 [#api-limits]
The limits of the Call Inspector RESTful APIs depend on the [pricing plan](/en/realtime-media/agora-analytics/reference/pricing) 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/sessions` or `/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 [#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 [#query-parameters]
The following query string parameters are required in the URL as search criteria:
| Parameter | Type | Description |
| ----------- | ------ | ----------------------------------------------------------------------------------------------- |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 [#http-request-example]
```html
GET /beta/analytics/call/lists?start_ts=1550024508&end_ts=1550025508&appid=xxxxxxxxxxxxxxxxxxxx&page_no=1&page_size=20 HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response example [#response-example]
```json
{
"code": 0,
"message": "string",
"requestId": "15c99xxxxxxxxxxx9be9b",
"total_size": 101,
"page_no": 1,
"page_size": 20,
"has_more": true,
"call_lists": [
{
"call_id": "cxxxxxxxxxxxxxxxxxxxx",
"cname": "cname1",
"created_ts": 1547448383,
"destroyed_ts": 1547448483,
"finished": true,
"call_pcu": 2,
"call_acu": 2,
"call_audio_freeze_rate": 0.12,
"call_video_freeze_rate": 0.07
}
]
}
```
Where:
* `code`: Number. The [status code](#status-codes).
* `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 in `call_lists`.
* `true` Indicates that some calls that meet the search criteria are not listed.
* `false` Indicates that all calls that meet the query criteria are listed.
If the call you need is not in `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 [#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 [#query-parameters-1]
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. To implement pagination, specify values 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 use-case. Therefore, if you specify 10 user IDs in the request, 10 or more user IDs are returned. |
| `appid` | String | [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 [#http-request-example-1]
```html
GET /beta/analytics/call/sessions?start_ts=1548665345&end_ts=1548670821&appid=axxxxxxxxxxxxxxxxxxxx&call_id=cxxxxxxxxxxxxxxxxxxxx&page_no=1&page_size=20&uids=uxx1,uxx2 HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response example [#response-example-1]
```json
{
"code": 0,
"message": "string",
"requestId": "15c99xxxxxxxxxxx9be9b",
"total_size": 101,
"page_no": 1,
"page_size": 20,
"call_info": [
{
"sid": "xxxxxxxxxxxxxxxxxxx",
"cname": "cname1",
"uid": 1234567,
"account": "UserA",
"network": "LAN",
"platform": "Linux",
"speaker": false,
"roles": [
"SPEAKER",
"SCREEN_SHARER"
],
"sdk_version": "2.3.3.150",
"device_type": "Linux version 4.14.255-311-248.529.amzn2.x86_64 (mockbuild@ip-10",
"join_ts": 1692584005,
"leave_ts": 1692584015,
"finished": true,
"user_audio_freeze_rate": 0.01,
"user_video_freeze_rate": 0.03
}
]
}
```
Where:
* `code`: Number. The [status code](#status-codes).
* `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 in `call_lists`.
* `true` Indicates that some calls that meet the search criteria are not listed.
* `false` Indicates that all calls that meet the query criteria are listed.
If the call you need is not in `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 [#get-quality-metrics]
Gets the quality metrics of a specified call.
* Method: `GET`
* Endpoint: `/beta/analytics/call/metrics`
#### Query parameters [#query-parameters-2]
The following query string parameters are required in the URL to specify the call:
| Parameter | Type | Description |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appid` | String | [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 [#http-request-example-2]
```html
GET /beta/analytics/call/metrics?start_ts=1548665345&end_ts=1548670821&appid=axxxxxxxxxxxxxxxxxxxx&call_id=cxxxxxxxxxxxxxxxxxxxx&sids=sxxxxxxxxxxxxxxxx1,sxxxxxxxxxxxxxxxx2,sxxxxxxxxxxxxxxxx3 HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response example [#response-example-2]
```json
{
"code": 200,
"message": "",
"requestId": "bxxxxxxxxxxxxxxxxxx4",
"metrics": [
{
"sid": "EDB224CCF4FB4F99815C24302BDF3301",
"data": [
{
"mid": 20003,
"kvs": [
[
1548670255,
215
],
[
1548670257,
129
],
[
1548670259,
121
]
],
"peer_uid": 0
}
]
}
]
}
```
* `code`: Number. The [status code](#status-codes).
* `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](#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 [#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 [#query-parameters-3]
The following query string parameters are required in the URL to specify the call ID and statistics:
| Parameter | Type | Description |
| ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appid` | String | [App ID](/en/realtime-media/agora-analytics/reference/glossary#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. Supported values: `country` (Nation); `region` (Area); `net` (Network type); `sdk` (SDK version); `os` (Operating system); `device` (Device model). |
| `metric` | String | Supported values: `audio_freeze_rate` (Audio stuttering rate); `video_freeze_rate` (Video freeze rate). |
#### HTTP request example [#http-request-example-3]
```html
curl --request GET \
--url https://api.sd-rtn.com/beta/analytics/call/statistics \
--header 'Accept: application/json' \
--header 'Authorization: Basic 123'
```
#### Response example [#response-example-3]
```json
{
"code": 200,
"message": "Success request: /beta/analytics/call/statistics",
"requestId": "191xxxxxxxxxxxxxxxx0f",
"data": [
{
"dimension_value": "3.7.1.247",
"user_count": 6,
"value": 0.007
}
]
}
```
Where:
* `code`: Number. The [status code](#status-codes).
* `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 [#retrieve-audiovideo-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 [#query-parameters-4]
The following query string parameters are required in the URL to specify the call ID and statistics:
| Parameter | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `appid` | String | [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 | Supported values: `audio_freeze_rate` (Audio stuttering rate); `video_freeze_rate` (Video freeze rate). |
#### HTTP request example [#http-request-example-4]
```html
curl --request GET \
--url https://api.sd-rtn.com/beta/analytics/call/freeze/bucket \
--header 'Accept: application/json' \
--header 'Authorization: Basic 123'
```
#### Response example [#response-example-4]
```json
{
"code": 200,
"message": "Success request: /beta/analytics/call/freeze/bucket",
"requestId": "1f7a7xxxxxxxxxxxxxxxe89d",
"data": [
{
"bucket": "[3%,5%)",
"user_count": 1
},
{
"bucket": "[0%,3%)",
"user_count": 19
}
]
}
```
Where:
* `code`: Number. The [status code](#status-codes).
* `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 [#retrieve-insight-statistics]
This method gets the insight statistics for a specific.
* Method: `GET`
* Endpoint: `/beta/analytics/call/statistics/time`
#### Query parameters [#query-parameters-5]
The following query string parameters are required in the URL to specify the call ID and statistics:
| Parameter | Type | Description |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appid` | String | [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 | Supported values: `user_count` (Number of participants in a call. Each user ID counts as one participant per channel and as multiple participants across different channels); `audio_freeze_rate` (Audio stuttering rate); `video_freeze_rate` (Video freeze rate); `audio_freeze_user_count` (Number of participants experiencing audio freezes); `video_freeze_user_count` (Number of participants experiencing video freezes). |
#### HTTP request example [#http-request-example-5]
```html
curl --request GET \
--url https://api.sd-rtn.com/beta/analytics/call/statistics/time \
--header 'Accept: application/json' \
--header 'Authorization: Basic 123'
```
#### Response example [#response-example-5]
```json
{
"code": 200,
"message": "Success request: /beta/analytics/call/statistics/time",
"requestId": "139dxxxxxxxxxxxxxxxxe968",
"data": [
{
"ts": 1692584160,
"value": 0
},
{
"ts": 1692584340,
"value": 0.007
},
{
"ts": 1692584100,
"value": 0
},
{
"ts": 1692584460,
"value": 0.003
},
{
"ts": 1692584400,
"value": 0.005
},
{
"ts": 1692584580,
"value": 0.05
}
]
}
```
Where:
* `code`: Number. The [status code](#status-codes).
* `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 [#data-insights]
With the Data Insights RESTful APIs, you can query the usage and quality metrics within a specified time frame.
### API limits [#api-limits-1]
The limits of the Data Insights RESTful APIs depend on the [pricing plan](/en/realtime-media/agora-analytics/reference/pricing) 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 [#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 [#query-parameters-6]
The following query string parameters are required in the URL:
| Parameter | Type | Description |
| :--------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 | Supported values: `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 users); `totalVideoDuration` (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 | Supported values: `1d` (By day. Returns data for the entire day starting from UTC 00:00 within the query time range); `1h` (By hour. Returns data for each whole UTC hour within the query time range). |
For more information about calculating by the number of users, see [How does Agora calculate service minutes?](/en/realtime-media/agora-analytics/reference/billing-policies#how-does-agora-calculate-service-minutes)
#### HTTP request example [#http-request-example-6]
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:
```html
GET /beta/insight/usage/by_time?startTs=1625097600&endTs=1625270400&appid=axxxxxxxxxxxxxxxxxxxx&metric=userCount&aggregateGranularity=1d HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response example [#response-example-6]
The response for the previous HTTP request example is as follows:
```json
{
"code": 200,
"message": "success",
"data": [
{
"userCount": 42,
"ts": 1625155200
},
{
"userCount": 37,
"ts": 1625241600
}
]
}
```
#### Response parameters [#response-parameters]
| Parameter | Type | Description |
| :-------- | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Number | The [status code](#status-codes). |
| `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 metric value. In the previous request example, two JSON objects are returned: one for 12:00 am on July 2, 2021, and one for 12:00 am on July 3, 2021. Fields: `userCount` (Number. The total number of users across all channels); `ts` (Number. Unix timestamp). |
### Query time-series quality metrics [#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 [#query-parameters-7]
The following query string parameters are required in the URL:
| Parameter | Type | Description |
| :--------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 | Supported values: `joinSuccessRate` (The rate at which users attempting to join any channel succeed, equal to number of users who joined divided by number of attempts to join); `joinSuccessIn5sRate` (The rate at which users attempting to join any channel succeed within 5 seconds, equal to number of users who joined within 5 seconds divided by number of attempts to join); `audioFreezeRate` (The rate at which audio freezing occurs, equal to total audio freeze time divided by 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, equal to total video freeze time divided by 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, equal to total end-to-end network delay divided by 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 | Supported values: `1d` (By day. Returns data for the entire day starting from UTC 00:00 within the query time range); `1h` (By hour. Returns data for each whole UTC hour within the query time range). |
| `productType` | String | Supported values: `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?](/en/realtime-media/agora-analytics/reference/billing-policies#how-does-agora-calculate-service-minutes)
#### HTTP request example [#http-request-example-7]
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:
```html
GET /beta/insight/quality/by_time?startTs=1625097600&endTs=1625184000&appid=axxxxxxxxxxxxxxxxxxxx&metric=networkDelay&aggregateGranularity=1h&productType=Native HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response example [#response-example-7]
The response for the previous HTTP request example is as follows:
```json
{
"code": 200,
"message": "success",
"data": [
{
"networkDelay": 0.064762,
"ts": 1625097600
},
{
"networkDelay": 0.028156,
"ts": 1625101200
},
...
{
"networkDelay": 0.03765,
"ts": 1625184000
}
]
}
```
#### Response parameters [#response-parameters-1]
| Parameter | Type | Description |
| :-------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Number | The [status code](#status-codes). |
| `message` | String | The success or error message. |
| `data` | JSONArray | Each JSON object contains a Unix timestamp for every hour within the specified time frame and the corresponding metric value. In the previous request example, 25 JSON objects are returned, from 8:00 am on July 1, 2021 through 8:00 am on July 2, 2021. Fields: `networkDelay` (Number. The network delay rate); `ts` (Number. Unix timestamp). |
### Query aggregated usage metrics [#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 [#query-parameters-8]
The following query string parameters are required in the URL:
| Parameter | Type | Description |
| :-------- | :----- | :------------------------------------------------------------------------------------------ |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#app-id) of your project. |
#### Body parameters [#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 | Supported values: `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 users); `totalVideoDuration` (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) Aggregation dimension. Supported values: `country`, `region`, `net`, `sdk`, `os`, `device`. If you set this parameter, the request returns the top 20 values in the dimension by default, or the top 50 values for `device`. When `metric` is `peakConcurrentUsers` or `peakConcurrentChannels`, `dimension` and `dimensionValues` are not supported, and the request returns aggregated results only by App ID. |
| `dimensionValues` | String | (Optional) Values for the specified dimension. This parameter is valid only when `dimension` is set. Enclose all values in double quotes and separate them with commas. If you set this parameter, the request returns aggregated metric data for the specified values. To discover top values first, omit `dimensionValues` in an initial request, then choose values from the results for later requests. |
| `filters` | JSONArray | (Optional) Region filters used to filter results by country. This parameter is valid only when `dimension` is `region`. It includes `name` (String. Only `country` is supported) and `value` (String. The country to filter by. Only one country value is supported). |
#### HTTP Request example [#http-request-example-8]
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**
```html
POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
{
"startTs": 1625097600,
"endTs": 1625184000,
"metric": "userCount",
"dimension": "country"
}
```
**Example 2: Query the number of calls for SDK versions 3.6.1.1 and 4.1.1**
```html
POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
{
"startTs": 1625097600,
"endTs": 1625184000,
"metric": "userCount",
"dimension": "sdkVersion",
"dimensionValues":["3.6.1.1","4.1.1"]
}
```
**Example 3: Query the top 20 regions in China with the highest number of calls and their respective call counts**
```html
POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
{
"startTs": 1625097600,
"endTs": 1625184000,
"metric": "userCount",
"dimension": "region",
"filters": [{"name": "country", "value": "China"}]
}
```
#### Response parameters [#response-parameters-2]
| Parameter | Type | Description |
| :-------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Number | The [status code](#status-codes). |
| `message` | String | The success or error message. |
| `data` | JSONArray | If the request does not include `dimension`, the response returns metric data aggregated by App ID. If the request includes `dimension`, the response returns an array containing the dimension values and metric data. |
#### Response example [#response-example-8]
**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.
```json
{
"code": 200,
"message": "null",
"data": [
{
"country": "China",
"userCount": 42,
},
{
"country": "United States",
"userCount": 37
}
......
]
}
```
**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.
```json
{
"code": 200,
"message": "null",
"data": [
{
"sdkVersion": "3.6.1.1",
"userCount": 42,
},
{
"sdkVersion": "4.1.1",
"userCount": 37
}
]
}
```
**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.
```json
{
"code": 200,
"message": "null",
"data": [
{
"region": "Shanghai",
"userCount": 42,
},
{
"region": "Beijing",
"userCount": 37
}
......
]
}
```
### Query aggregated quality metrics [#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 [#query-parameters-9]
The following query string parameters are required in the URL:
| Parameter | Type | Description |
| :-------- | :----- | :------------------------------------------------------------------------------------------ |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#app-id) of your project. |
#### Body parameters [#body-parameters-1]
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 | Supported values: `joinSuccessRate` (The rate at which users attempting to join any channel succeed, equal to number of users who joined divided by number of attempts to join); `joinSuccessIn5sRate` (The rate at which users attempting to join any channel succeed within 5 seconds, equal to number of users who joined within 5 seconds divided by number of attempts to join); `audioFreezeRate` (The rate at which audio freezing occurs, equal to total audio freeze time divided by 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, equal to total video freeze time divided by 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, equal to total end-to-end network delay divided by 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) Aggregation dimension. Supported values: `country`, `region`, `net`, `sdk`, `os`, `device`, `channelSize`. If you set this parameter, the request returns the top 20 values in the dimension by default, or the top 50 values for `device`. When `metric` is `peakConcurrentUsers` or `peakConcurrentChannels`, `dimension` and `dimensionValues` are not supported, and the request returns aggregated results only by App ID. |
| `dimensionValues` | String | (Optional) Values for the specified dimension. This parameter is valid only when `dimension` is set. Enclose all values in double quotes and separate them with commas. If you set this parameter, the request returns aggregated metric data for the specified values. To discover top values first, omit `dimensionValues` in an initial request, then choose values from the results for later requests. When `dimension` is `channelSize`, `dimensionValues` is not supported and the results are grouped by the preset gradient scale. |
| `filters` | JSONArray | (Optional) Region filters used to filter results by country. This parameter is valid only when `dimension` is `region`. It includes `name` (String. Only `country` is supported) and `value` (String. The country to filter by. Only one country value is supported). |
#### HTTP Request example [#http-request-example-9]
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**
```html
POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
{
"startTs": 1625097600,
"endTs": 1625184000,
"metric": "audioFreezeRate",
"dimension": "country"
}
```
**Example 2: Query the audio freeze rates for SDK versions 3.6.1.1 and 4.1.1**
```html
POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
{
"startTs": 1625097600,
"endTs": 1625184000,
"metric": "audioFreezeRate",
"dimension": "sdkVersion",
"dimensionValues":["3.6.1.1","4.1.1"]
}
```
**Example 3: Query the top 20 regions in China with the highest audio freeze rates and their respective audio freeze rate**
```html
POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
{
"startTs": 1625097600,
"endTs": 1625184000,
"metric": "audioFreezeRate",
"dimension": "region",
"filters": [{"name": "country", "value": "China"}]
}
```
#### Response parameters [#response-parameters-3]
| Parameter | Type | Description |
| :-------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Number | The [status code](#status-codes). |
| `message` | String | The success or error message. |
| `data` | JSONArray | If the `dimension` field is not filled in the request, returns the metric data of the App ID dimension. If the `dimension` field is filled in the request, returns an array composed of dimensions, `refUsage`, and metric data. `refUsage` is auxiliary usage data. In each returned data group, each `metric` corresponds to auxiliary usage data used to assist in determining data validity. When `metric` is `joinSuccessRate` or `joinSuccessIn5sRate`, `refUsage` represents the number of attempts to join the channel. When `metric` is `audioFreezeRate` or `videoFreezeRate`, `refUsage` represents the duration of audio calls or video calls in minutes. When `metric` is `networkDelay`, `refUsage` represents the total duration of audio and video calls in minutes. |
#### Response example [#response-example-9]
**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.
```json
{
"code": 200,
"message": "null",
"data": [
{
"country": "China",
"refUsage": 231234,
"audioFreezeRate": 0.0017,
},
{
"country": "United States",
"refUsage": 213212,
"audioFreezeRate": 0.0014
}
......
]
}
```
**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.
```json
{
"code": 200,
"message": "null",
"data": [
{
"sdkVersion": "3.6.1.1",
"refUsage": 231234,
"audioFreezeRate": 0.0017,
},
{
"sdkVersion": "4.1.1",
"refUsage": 213212,
"audioFreezeRate": 0.0014
}
]
}
```
**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.
```json
{
"code": 200,
"message": "null",
"data": [
{
"region": "Shanghai",
"refUsage": 231234,
"audioFreezeRate": 0.0017,
},
{
"region": "Beijing",
"refUsage": 213212,
"audioFreezeRate": 0.0014
}
......
]
}
```
## Real-time Monitoring [#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 [#api-limits-2]
The limits of the Real-time Monitoring RESTful APIs depend on the [pricing plan](/en/realtime-media/agora-analytics/reference/pricing) 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 [#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 [#query-parameters-10]
The following query string parameters are required in the URL:
| **Parameter** | Type | **Description** |
| :---------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 | Supported values: `Native` (The Agora Video SDK for Android, iOS, macOS, and Windows); `WebRTC` (The Agora Video SDK for Web). |
| `metric` | String | Supported values: `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) Aggregation dimension. Supported values: `country`, `region`, `net`, `sdk`, `os`, `device`. To obtain the top values for the current `dimension`, query [top 20 real-time scale metrics](#20scale), then choose values from the results and pass them in `dimensionValues` in later 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 [#http-request-example-10]
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:
```html
GET /beta/realtime/usage/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=your_app_id&productType=Native&metric=userCount&dimension=sdk&dimensionValues="3.6.1.1","4.1.1" HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response parameters [#response-parameters-4]
The response contains the following fields:
| Field | Type | Description |
| :-------- | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Number | The [status code](#status-codes). `200` indicates that the request is successful. |
| `message` | String | The error message. |
| `data` | JSONArray | An array consisting of the requested `metric` field and `ts`, which is the Unix timestamp of the start point of the corresponding time window. |
#### Response example [#response-example-10]
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
```json
{
"code": 200,
"message": null,
"data": [
{
"userCount": 236,
"sdk": "3.6.1.1",
"ts": 1631837400
},
{
"userCount": 82,
"sdk": "4.1.1",
"ts": 1631837400
},
{
"userCount": 235,
"sdk": "3.6.1.1",
"ts": 1631837420
},
{
"userCount": 85,
"sdk": "4.1.1",
"ts": 1631837420
},
{
"userCount": 252,
"sdk": "3.6.1.1",
"ts": 1631837440
},
{
"userCount": 90,
"sdk": "4.1.1",
"ts": 1631837440
}
]
}
```
### Query real-time quality metrics [#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 [#query-parameters-11]
The following query string parameters are required in the URL:
| Parameter | Type | Description |
| :---------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 | Supported values: `Native` (The Agora Video SDK for Android, iOS, macOS, and Windows); `WebRTC` (The Agora Video SDK for Web). |
| `metric` | String | Supported values: `joinSuccessRate` (The rate at which users attempting to join any channel succeed, equal to number of users who joined divided by number of attempts to join); `joinSuccessIn5sRate` (The rate at which users attempting to join any channel succeed within 5 seconds, equal to number of users who joined within 5 seconds divided by number of attempts to join); `audioFreezeRate` (The rate at which audio freezing occurs, equal to total audio freeze time divided by 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, equal to total video freeze time divided by 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, equal to total end-to-end network delay divided by 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) Aggregation dimension. Supported values: `country`, `region`, `net`, `sdk`, `os`, `device`. To obtain the top values for the current `dimension`, query [top 20 real-time quality metrics](#20quality), then choose values from the results and pass them in `dimensionValues` in later 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 [#http-request-example-11]
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**
```html
GET /beta/realtime/usage/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=axxxxxxxxxxxxxxxxxxxx&productType=Native&metric=networkDelay HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
**Example 2: `uids` is specified as `2303692334` and `2963430861`**
```html
GET /beta/realtime/usage/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=axxxxxxxxxxxxxxxxxxxx&productType=Native&metric=networkDelay&cname=demoChannel&uids=2303692334,2963430861 HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
**Example 3: `dimension` is specified as `sdkVersion`, and `dimensionValues` as `3.6.1.1` and `4.1.1`**
```html
GET /beta/realtime/quality/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=your_app_id&productType=Native&metric=networkDelay&dimension=sdk&dimensionValues="3.6.1.1","4.1.1" HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response parameters [#response-parameters-5]
The response contains the following fields:
| Field | Type | Description |
| :-------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Number | The [status code](#status-codes). `200` indicates that the request is successful. |
| `message` | String | The error message. |
| `data` | JSONArray | - The request does not include the `uids` field: An array of metric data and Unix timestamps (in seconds).`; `The request includes the `uids` field: An array of `uid`, metric data, and Unix timestamps (in seconds).`; `The request includes the `dimension` and `dimensionValues` fields: Arrays of metric data, dimensions, and Unix timestamps (in seconds). |
#### Response example [#response-example-11]
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**
```json
{
"code": 200,
"message": "success",
"data": [
{
"networkDelay": 0.0120,
"ts": 1631837400
},
{
"networkDelay": 0.0057,
"ts": 1631837420
},
{
"networkDelay": 0.0039,
"ts": 1631837440
}
]
}
```
**Example 2: `uids` is specified as `2303692334` and `2963430861`**
```json
{
"code": 200,
"message": "success",
"data": [
{
"uid": 2303692334,
"values": [
{
"ts": 1631837400,
"networkDelay": 0.389
},
{
"ts": 1631837420,
"networkDelay": 0.389
},
{
"ts": 1631837440,
"networkDelay": 0.389
}
]
},
{
"uid": 2963430861,
"values": [
{
"ts": 1631837400,
"networkDelay": 0.389
},
{
"ts": 1631837420,
"networkDelay": 0.389
},
{
"ts": 1631837440,
"networkDelay": 0.389
}
]
}
]
}
```
**Example 3: `dimension` is specified as `sdkVersion`, and `dimensionValues` as `3.6.1.1` and `4.1.1`**
```json
{
"code": 200,
"message": null,
"data": [
{
"networkDelay": 0.389,
"sdk": "3.6.1.1",
"ts": 1631837400
},
{
"networkDelay": 0.411,
"sdk": "4.1.1",
"ts": 1631837400
},
{
"networkDelay": 0.343,
"sdk": "3.6.1.1",
"ts": 1631837420
},
{
"networkDelay": 0.363,
"sdk": "4.1.1",
"ts": 1631837420
},
{
"networkDelay": 0.511,
"sdk": "3.6.1.1",
"ts": 1631837440
},
{
"networkDelay": 0.436,
"sdk": "4.1.1",
"ts": 1631837440
}
]
}
```
### Query top 20 real-time scale metrics [#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](#realtimescale).
* Method: `GET`
* Endpoint: `/beta/realtime/usage/dimension/top20`
#### Query parameters [#query-parameters-12]
The following query string parameters are required in the URL:
| **Parameter** | Type | **Description** |
| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 | Supported values: `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 | Aggregation dimension. Supported values: `country`, `region`, `net`, `sdk`, `os`, `device`. The request returns the top 20 values in the dimension by default, or the top 50 values for `device`. |
#### Request example [#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:
```html
GET /beta/realtime/usage/dimension/top20?ts=1631837410&appid=your_app_id&productType=Native&metric=userCount&dimension=sdk HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response parameters [#response-parameters-6]
The response contains the following fields:
| Field | Type | Description |
| :-------- | :-------- | :-------------------------------------------------------------------------------------------------------------------- |
| `code` | Number | The [status code](#status-codes). `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 [#response-example-12]
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.
```json
{
"code": 200,
"message": null,
"data": {
"list": [
{
"sdk": "3.6.1.1",
"userCount": 236,
"windowStartTs": 1631837410,
"windowEndTs": 1631837430
},
{
"sdk": "4.1.1",
"userCount": 82,
"windowStartTs": 1631837410,
"windowEndTs": 1631837430
},
{
"sdk": "2.9.1",
"userCount": 68,
"windowStartTs": 1631837410,
"windowEndTs": 1631837430
},
...
]
}
}
```
### Query top 20 real-time quality metrics [#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](#realtimequality).
* Method: `GET`
* Endpoint: `/beta/realtime/quality/dimension/top20`
#### Query parameters [#query-parameters-13]
The following query string parameters are required in the URL:
| **Parameter** | Type | **Description** |
| :------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appid` | String | The [App ID](/en/realtime-media/agora-analytics/reference/glossary#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 | Supported values: `Native` (The Agora Video SDK for Android, iOS, macOS, and Windows); `WebRTC` (The Agora Video SDK for Web). |
| `metric` | String | Supported values: `joinSuccessRate` (The rate at which users attempting to join any channel succeed, equal to number of users who joined divided by number of attempts to join); `joinSuccessIn5sRate` (The rate at which users attempting to join any channel succeed within 5 seconds, equal to number of users who joined within 5 seconds divided by number of attempts to join); `audioFreezeRate` (The rate at which audio freezing occurs, equal to total audio freeze time divided by 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, equal to total video freeze time divided by 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, equal to total end-to-end network delay divided by 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 | Aggregation dimension. Supported values: `country`, `region`, `net`, `sdk`, `os`, `device`. The request returns the top 20 values in the dimension by default, or the top 50 values for `device`. |
| `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 [#request-example-1]
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:
```html
GET /beta/realtime/quality/dimension/top20?ts=1671624000&appid=your_app_id&productType=Native&metric=audioFreezeRate&dimension=device&extraMetrics=userCount HTTP/1.1
Host: api.agora.io
Accept: application/json
Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
```
#### Response parameters [#response-parameters-7]
The response contains the following fields:
| Field | Type | Description |
| :-------- | :-------- | :-------------------------------------------------------------------------------------------------------------------- |
| `code` | Number | The [status code](#status-codes). `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 [#response-example-13]
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.
```json
{
"code": 200,
"message": null,
"data": {
"list": [
{
"audioFreezeRate": 0.050833333333333335,
"windowStartTs": 1671624000,
"userCount": 2,
"device": "ldn-al00",
"windowEndTs": 1671624020
},
{
"audioFreezeRate": 0,
"windowStartTs": 1671624000,
"userCount": 2,
"device": "80HH",
"windowEndTs": 1671624020
},
{
"audioFreezeRate": 0,
"windowStartTs": 1671624000,
"userCount": 1,
"device": "20KNA004CD",
"windowEndTs": 1671624020
}
]
}
}
```
## References [#references]
### Status codes [#status-codes]
| Code | Description |
| ----- | ----------------------------------------------------------------- |
| `200` | The request is successful. |
| `300` | The API limits are exceeded ([Call Search](#call-inspector) 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 [#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. | | |