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:

Call Inspector
Data Insights
Real-time Monitoring

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/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

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

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

{
  "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.
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

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. 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 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

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

{
  "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.
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

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

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

{
  "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.
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. 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

curl --request GET \
  --url https://api.sd-rtn.com/beta/analytics/call/statistics \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic 123'

Response example

{
  "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.
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	Supported values: `audio_freeze_rate` (Audio stuttering rate); `video_freeze_rate` (Video freeze rate).

HTTP request example

curl --request GET \
  --url https://api.sd-rtn.com/beta/analytics/call/freeze/bucket \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic 123'

Response example

{
  "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.
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	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

curl --request GET \
  --url https://api.sd-rtn.com/beta/analytics/call/statistics/time \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic 123'

Response example

{
  "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.
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	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 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?

HTTP request example

The following example queries the total number of users across all channels starting from 8

am on July 1, 2021 to 8

am on July 3, 2021:

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

The response for the previous HTTP request example is as follows:

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "userCount": 42,
            "ts": 1625155200
        },
        {
            "userCount": 37,
            "ts": 1625241600
        }
   ]
}

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 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 am on July 2, 2021, and one for 12 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

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	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 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?

HTTP request example

The following example queries the hourly network delay rate starting from 8

am on July 1, 2021 to 8

am on July 2, 2021:

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

The response for the previous HTTP request example is as follows:

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "networkDelay": 0.064762,
            "ts": 1625097600
        },
        {
            "networkDelay": 0.028156,
            "ts": 1625101200
        },
        ...
        {
            "networkDelay": 0.03765,
            "ts": 1625184000
        }
   ]
}

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 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 am on July 1, 2021 through 8 am on July 2, 2021. Fields: `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	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

The following examples query the total number of users across all channels starting from 8

am on July 1, 2021 to 8

am on July 2, 2021:

Example 1: Query the top 20 countries with the highest number of calls and their respective call counts

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

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

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

Parameter	Type	Description
`code`	Number	The status code.
`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

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

am on July 1, 2021 and 8

am on July 2, 2021.

{
    "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

am on July 1, 2021 and 8

am on July 2, 2021 for SDK versions 3.6.1.1 and 4.1.1 respectively.

{
    "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

am on July 1, 2021 and 8

am on July 2, 2021.

{
    "code": 200,
    "message": "null",
    "data": [
        {
            "region": "Shanghai",
            "userCount": 42,
        },
        {
            "region": "Beijing",
            "userCount": 37
        }
        ......
   ]
}

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	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

The following examples query the audio freeze rate across all channels starting from 8

am on July 1, 2021 to 8

am on July 2, 2021:

Example 1: Query the top 20 countries with the highest audio freeze rates and their respective audio freeze rate

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

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

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

Parameter	Type	Description
`code`	Number	The status code.
`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

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

am on July 1, 2021 and 8

am on July 2, 2021.

{
    "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

am on July 1, 2021 and 8

am on July 2, 2021 for SDK versions 3.6.1.1 and 4.1.1 respectively.

{
    "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

am on July 1, 2021 and 8

am on July 2, 2021.

{
    "code": 200,
    "message": "null",
    "data": [
        {
            "region": "Shanghai",
            "refUsage": 231234,
            "audioFreezeRate": 0.0017,
        },
        {
            "region": "Beijing",
            "refUsage": 213212,
            "audioFreezeRate": 0.0014
        }
        ......
   ]
}

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

. For example, [00:00

, 00:00

] is a time window, while [00:00

, 00:00

] 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	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, 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

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

on September 17, 2021 and endTs set to 08:11

on the same day. The HTTP request is as follows:

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

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 requested `metric` field and `ts`, which is 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:10
] on September 17, 2021
[00:10
, 00:10
] on September 17, 2021
[00:10
, 00:11
] on September 17, 2021

{
    "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

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	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, 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

The following example queries the network delay rate from 00:10

to 00:11

on September 17, 2021:

Example 1: uids is not specified

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

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

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

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	- 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

For the previous HTTP request example, the response includes data of the following time windows:

[00:10
, 00:10
] on September 17, 2021
[00:10
, 00:10
] on September 17, 2021
[00:10
, 00:11
] on September 17, 2021

Example 1: uids is not specified

{
    "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

{
    "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

{
    "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

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	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

The following example queries the top 20 number of users for each SDK version starting from 08:10

on September 17, 2021 is as follows:

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

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

to 08:10

on September 17, 2021.


{
    "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

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	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

The following example passes in extraMetrics and queries the top 50 audio freeze rate values for each device starting from 20:00

on December 21, 2022:

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

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

to 20:00

on December 21, 2022.

{
    "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

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.

Contact Us

Contact Us