Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

Analytics REST API reference

Before working with the RESTful APIs, review the Agora Analytics features in Agora Console to gain a visual understanding of the quality and usage metrics that are available. For details, see the following user guides:

To use Agora Analytics RESTful APIs, subscribe to an Agora Analytics pricing plan.

Authentication

Before using the Agora RESTful API, you need to pass the basic HTTP authentication.

Data format

All requests are sent to the host: api.agora.io.

  • Request: The request uses query string parameters in the URL.
  • Response: The response content is in JSON format.

Call Inspector

With the Call Inspector RESTful APIs, you can search for calls with quality issues and obtain detailed metrics about call quality.

API limits

The limits of the Call Inspector RESTful APIs depend on the pricing plan you subscribe to.

The Starter, Standard, Premium, and Enterprise pricing plans have the following differences in terms of API limits:

  • Request frequency is calculated using the server's UTC time.
  • Data delay refers to the time required from the generation of data to the point where it can be queried.
    • Endpoint is /beta/analytics/call/lists:
    StarterStandardPremiumEnterprise
    Request frequencyN/ANo more than 1/second and 1,000/dayNo more than 3/second and 2,000/dayNo more than 10/second and 10,000/day
    Available dataN/AWithin the past 1 dayWithin the past 7 daysWithin the past 15 days
    Response contentN/AA maximum of 8 hours of dataA maximum of 16 hours of dataA maximum of 24 hours of data
    Data delayN/A60 seconds20 seconds20 seconds
    • Endpoint is /beta/analytics/call/sessions or /beta/analytics/call/metrics:
    StarterStandardPremiumEnterprise
    Request frequencyN/ANo more than 1/second and 1,000/dayNo more than 3/second and 2,000/dayNo more than 10/second and 10,000/day
    Available dataN/AWithin the past 1 dayWithin the past 7 daysWithin the past 15 days
    Response contentN/AA maximum of 1 hours of dataA maximum of 3 hours of dataA maximum of 6 hours of data
    Data delayN/A300 seconds150 seconds100 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:

    ParameterTypeDescription
    start_tsNumberThe starting time of the search time frame. Unix time (in seconds since 1 January 1970) in UTC.
    end_tsNumberThe ending time of the search time frame. Unix time (in seconds since 1 January 1970) in UTC.
    cnameString(Optional) The channel name.
    appidStringApp ID of your project.
    page_noNumber(Optional) The page number. The default is 1.
    page_sizeNumber(Optional) The number of calls on each page. The default is 20 and the maximum is 100.

    HTTP request example


    _4
    GET /beta/analytics/call/lists?start_ts=1550024508&end_ts=1550025508&appid=xxxxxxxxxxxxxxxxxxxx&page_no=1&page_size=20 HTTP/1.1
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response example


    _18
    {
    _18
    "code": 200,
    _18
    "message": "",
    _18
    "requestId": "bxxxxxxxxxxxxxxxxxx4",
    _18
    "total_size": 101,
    _18
    "page_no": 1,
    _18
    "page_size": 20,
    _18
    "has_more": false,
    _18
    "call_lists": [
    _18
    {
    _18
    "call_id": "cxxxxxxxxxxxxxxxxxxxx",
    _18
    "cname": "cname1",
    _18
    "created_ts": 1547448383,
    _18
    "destroyed_ts": 1547448483,
    _18
    "finished": true
    _18
    }
    _18
    ]
    _18
    }

    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 represents that some calls that meet the search criteria are not 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.

    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:

    ParameterTypeDescription
    start_tsNumberThe starting time of the call. Unix time (in seconds since 1 January 1970) in UTC.
    end_tsNumberThe ending time of the call. Unix time (in seconds since 1 January 1970) in UTC.
    call_idStringThe unique ID of the call.
    page_noNumber(Optional) The page number. The default is 1.
    page_sizeNumber(Optional) The number of user sessions on each page. The default is 20 and the maximum is 100.
    To implement pagination, you need to specify a value for both page_no and page_size.
    uidsString(Optional) The list of user IDs separated by commas. For example, uids=10001,10002,10003. You can specify a maximum of 10 user IDs. A user ID may occur twice in the list according to the actual scenario. Therefore, if you specify 10 user IDs in the request, 10 or more user IDs are returned.
    appidStringApp ID of your project.
    exclude_server_userBoolean(Optional) Whether or not to exclude Linux users. true by default, which represents excluding Linux users.

    HTTP request example


    _4
    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
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response example


    _23
    {
    _23
    "code": 200,
    _23
    "message": "",
    _23
    "requestId": "bxxxxxxxxxxxxxxxxxx4",
    _23
    "total_size": 101,
    _23
    "page_no": 1,
    _23
    "page_size": 20,
    _23
    "call_info": [
    _23
    {
    _23
    "sid": "EDB224CCF4FB4F99815C24302BDF3301",
    _23
    "cname": "15056678066620",
    _23
    "uid": 630985881,
    _23
    "network": "Wi-Fi",
    _23
    "platform": "Android",
    _23
    "speaker": true,
    _23
    "sdk_version": "2.2.0.07_14",
    _23
    "device_type": "Android (6.0)",
    _23
    "join_ts": 1548670251,
    _23
    "leave_ts": 1548670815,
    _23
    "finished": true
    _23
    }
    _23
    ]
    _23
    }

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

    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:

    ParameterTypeDescription
    start_tsNumberThe starting time of the call. Unix time (in seconds since 1 January 1970) in UTC.
    end_tsNumberThe ending time of the call. Unix time (in seconds since 1 January 1970) in UTC.
    appidStringApp ID of your project.
    call_idStringThe unique ID of the call.
    sidsStringThe 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


    _4
    GET /beta/analytics/call/metrics?start_ts=1548665345&end_ts=1548670821&appid=axxxxxxxxxxxxxxxxxxxx&call_id=cxxxxxxxxxxxxxxxxxxxx&sids=sxxxxxxxxxxxxxxxx1,sxxxxxxxxxxxxxxxx2,sxxxxxxxxxxxxxxxx3 HTTP/1.1
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response example


    _30
    {
    _30
    "code": 200,
    _30
    "message": "",
    _30
    "requestId": "bxxxxxxxxxxxxxxxxxx4",
    _30
    "metrics": [
    _30
    {
    _30
    "sid": "EDB224CCF4FB4F99815C24302BDF3301",
    _30
    "data": [
    _30
    {
    _30
    "mid": 20003,
    _30
    "kvs": [
    _30
    [
    _30
    1548670255,
    _30
    215
    _30
    ],
    _30
    [
    _30
    1548670257,
    _30
    129
    _30
    ],
    _30
    [
    _30
    1548670259,
    _30
    121
    _30
    ]
    _30
    ],
    _30
    "peer_uid": 0
    _30
    }
    _30
    ]
    _30
    }
    _30
    ]
    _30
    }

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

    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:
    StarterStandardPremiumEnterprise
    Request frequencyN/AN/ANo more than 3/minute and 40/dayNo more than 10/minute and 60/day
    Available dataN/AN/AWithin the past 14 daysWithin the past 30 days
    Query time frameN/AN/ANo longer than 3 daysNo longer than 7 days
    Data granularityN/AN/APer day and hourPer day and hour
    Data delayN/AN/A12 hours6 hours
    • Endpoint is /beta/insight/quality/by_time:
    StarterStandardPremiumEnterprise
    Request frequencyN/AN/ANo more than 3/minute and 40/dayNo more than 10/minute and 60/day
    Available dataN/AN/AWithin the past 14 daysWithin the past 30 days
    Query time frameN/AN/ANo longer than 3 daysNo longer than 7 days
    Data granularityN/AN/APer day, hour, and minutePer day, hour, and minute
    Data delayN/AN/A6 hours6 hours
    • Endpoint is /beta/insight/usage/aggregation:
    StarterStandardPremiumEnterprise
    Request frequencyN/AN/ANo more than 3/minute and 40/dayNo more than 10/minute and 60/day
    Available dataN/AN/AWithin the past 14 daysWithin the past 30 days
    Data granularityN/AN/APer day and hourPer day and hour
    Data delayN/AN/A12 hours6 hours
    • Endpoint is /beta/insight/quality/aggregation:
    StarterStandardPremiumEnterprise
    Request frequencyN/AN/ANo more than 3/minute and 40/dayNo more than 10/minute and 60/day
    Available dataN/AN/AWithin the past 14 daysWithin the past 30 days
    Data granularityN/AN/APer day and hourPer day and hour
    Data delayN/AN/A6 hours6 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:

    ParameterTypeDescription
    startTsNumberThe start point (Unix timestamp) of the time frame to query.
    endTsNumberThe end point (Unix timestamp) of the time frame to query.
    appidStringThe App ID of your project.
    metricStringThe metrics you want to query. You can set it to one of the following:
  • userCount: The total number of users across all channels. A user joining the same channel with different user IDs or joining different channels with the same user ID is counted multiple times.
  • sessionCount: The total count of users joining channels. Each time any user ID joins any channel is counted.
  • channelCount: The total number of channels. A channel is counted once for each period between the time when the first user joins it and the time when the last user leaves it.
  • peakCurrentChannels: The maximum number of channels in use.
  • peakCurrentUsers: The maximum number of in-call users across channels.
  • totalDuration: The total duration of video and audio-only calls calculated by the number of 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
  • aggregateGranularityStringThe level of time-related detail in the returned data. You can only set it to 1d, which returns the values corresponding to 12:00 am (UTC) on each day within the specified time frame.
    For more information about calculating by the number of users, see How does Agora calculate service minutes?

    HTTP request example

    The following example queries the total number of users across all channels starting from 8:00 am on July 1, 2021 to 8:00 am on July 3, 2021:


    _4
    GET /beta/insight/usage/by_time?startTs=1625097600&endTs=1625270400&appid=axxxxxxxxxxxxxxxxxxxx&metric=userCount&aggregateGranularity=1d HTTP/1.1
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response parameters

    ParameterTypeDescription
    codeNumberThe status code.
    messageStringThe success or error message.
    dataJSONArrayEach JSON object contains a Unix timestamp representing 12:00 am (UTC) on each day within the specified time frame and the corresponding value of the specified metrics. In the case of the previous request example, two JSON objects should be returned: One for 12:00 am on July 2, 2021, the other for 12:00 am on July 3, 2021.
  • userCount: Number. The total number of users across all channels.
  • ts: Number. Unix timestamp.
  • Response example

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


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

    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:

    ParameterTypeDescription
    startTsNumberThe start point (Unix timestamp) of the time frame to query.
    endTsNumberThe end point (Unix timestamp) of the time frame to query.
    appidStringThe App ID of your project.
    metricStringThe metrics you want to query. You can set it to one of the following:
  • joinSuccessRate: The rate at which users attempting to join any channel succeed, which equals Number of users who have joined ÷ Number of attempts to join.
  • joinSuccessIn5sRate: The rate at which users attempting to join any channel succeed within 5 seconds, which equals Number of users who have joined within 5 seconds ÷ Number of attempts to join.
  • audioFreezeRate: The rate at which audio freezing occurs, which equals Total audio freeze time ÷ Total audio minutes calculated by the number of streams. Only audio freezes longer than 200 milliseconds are counted.
  • videoFreezeRate: The rate at which video freezing occurs, which equals Total video freeze time ÷ Total video minutes calculated by the number of streams. Only video freezes longer than 600 milliseconds are counted.
  • networkDelay: The rate at which network delay occurs, which equals Total end-to-end network delay ÷ Total audio and video minutes calculated by the number of streams. Only end-to-end network delays longer than 400 milliseconds are counted.
  • aggregateGranularityStringThe level of time-related detail in the returned data. You can set it to one of the following:
  • 1d, which returns the metrics corresponding to 12:00 am (UTC) on each day within the specified time frame.
  • 1h, which returns the metrics corresponding to every hour within the specified time frame.
  • productTypeStringThe product for which you want to query the metrics. You can set it to:
  • Native: The Agora Video SDK for Android, iOS, macOS, and Windows.
  • WebRTC: The Agora Video SDK for Web.
  • For more information about calculating by the number of streams, see How does Agora calculate service minutes?

    HTTP request example

    The following example queries the hourly network delay rate starting from 8:00 am on July 1, 2021 to 8:00 am on July 2, 2021:


    _4
    GET /beta/insight/quality/by_time?startTs=1625097600&endTs=1625184000&appid=axxxxxxxxxxxxxxxxxxxx&metric=networkDelay&aggregateGranularity=1h&productType=Native HTTP/1.1
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response parameters

    ParameterTypeDescription
    codeNumberThe status code.
    messageStringThe success or error message.
    dataJSONArrayEach JSON object contains a Unix timestamp representing every hour within the specified time frame and the corresponding value of the specified metrics. In the case of the previous request example, 25 JSON objects should be returned. The first one is for 8:00 am on July 1, 2021, the second for 9:00 am on July 1, 2021, and so on. The last one is for 8:00 am on July 2, 2021.
  • networkDelay: Number. The network delay rate.
  • ts: Number. Unix timestamp.
  • Response example

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


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

    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:

    ParameterTypeDescription
    appidStringThe App ID of your project.

    Body parameters

    The following query string parameters are required in the URL:

    ParameterTypeDescription
    startTsNumberThe start point (Unix timestamp) of the time frame to query.
    endTsNumberThe end point (Unix timestamp) of the time frame to query.
    metricStringThe metrics you want to query. You can set it to one of the following:
  • userCount: The total number of users across all channels. A user joining the same channel with different user IDs or joining different channels with the same user ID is counted multiple times.
  • sessionCount: The total count of users joining channels. Each time any user ID joins any channel is counted.
  • channelCount: The total number of channels. A channel is counted once for each period between the time when the first user joins it and the time when the last user leaves it.
  • peakCurrentChannels: The maximum number of channels in use.
  • peakCurrentUsers: The maximum number of in-call users across channels.
  • totalDuration: The total duration of video and audio-only calls calculated by the number of 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
  • dimensionString(Optional) The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed:
  • country: Country.
  • region: Region.
  • network: Network type.
  • sdkVersion: SDK version.
  • os: Operating system.
  • device: Device model.
  • If this parameter is set, the request will return the top 20 (top 50 for device dimension) values in the corresponding dimension by default.
    When the metric is set to peakConcurrentUsers or peakConcurrentChannels, specifying dimension and dimensionValues is not supported, and the request will only return aggregated results by App ID dimension.
    dimensionValuesString(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.
    You can obtain the top values for the current dimension by not specifying dimensionValues in the first request, and then select several values from the results based on your business needs to pass as the value of dimensionValues in subsequent requests.
    filtersJSONArray(Optional) The region filters used to filter results by country. This parameter is only valid when dimension is set to region. It is used to filter results from the region dimension to include only results that belong to the specified country. The following properties are included:
  • name: String. Only country is supported.
  • value: String. The country to be filtered, and only one country value is supported.
  • HTTP Request example

    The following examples query the total number of users across all channels starting from 8:00 am on July 1, 2021 to 8:00 am on July 2, 2021:

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


    _11
    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
    _11
    Host: api.agora.io
    _11
    Accept: application/json
    _11
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
    _11
    _11
    {
    _11
    "startTs": 1625097600,
    _11
    "endTs": 1625184000,
    _11
    "metric": "userCount",
    _11
    "dimension": "country"
    _11
    }

    Example 2: Query the number of calls for SDK versions 3.6.1.1 and 4.1.1


    _12
    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
    _12
    Host: api.agora.io
    _12
    Accept: application/json
    _12
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
    _12
    _12
    {
    _12
    "startTs": 1625097600,
    _12
    "endTs": 1625184000,
    _12
    "metric": "userCount",
    _12
    "dimension": "sdkVersion",
    _12
    "dimensionValues":["3.6.1.1","4.1.1"]
    _12
    }

    Example 3: Query the top 20 regions in China with the highest number of calls and their respective call counts


    _12
    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
    _12
    Host: api.agora.io
    _12
    Accept: application/json
    _12
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
    _12
    _12
    {
    _12
    "startTs": 1625097600,
    _12
    "endTs": 1625184000,
    _12
    "metric": "userCount",
    _12
    "dimension": "region",
    _12
    "filters": [{"name": "country", "value": "China"}]
    _12
    }

    Response parameters

    ParameterTypeDescription
    codeNumberThe status code.
    messageStringThe success or error message.
    dataJSONArray
  • If the dimension field is not included in the request: Return the metric data for the App ID dimension.
  • If the dimension field is included in the request: Return an array consisting of dimensions and metric data.
  • Response example

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

    Contains 20 sets of data, each representing the top 20 countries with the highest total number of calls between 8:00 am on July 1, 2021 and 8:00 am on July 2, 2021.


    _15
    {
    _15
    "code": 200,
    _15
    "message": "null",
    _15
    "data": [
    _15
    {
    _15
    "country": "China",
    _15
    "userCount": 42,
    _15
    },
    _15
    {
    _15
    "country": "United States",
    _15
    "userCount": 37
    _15
    }
    _15
    ......
    _15
    ]
    _15
    }

    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.


    _14
    {
    _14
    "code": 200,
    _14
    "message": "null",
    _14
    "data": [
    _14
    {
    _14
    "sdkVersion": "3.6.1.1",
    _14
    "userCount": 42,
    _14
    },
    _14
    {
    _14
    "sdkVersion": "4.1.1",
    _14
    "userCount": 37
    _14
    }
    _14
    ]
    _14
    }

    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.


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

    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:

    ParameterTypeDescription
    appidStringThe App ID of your project.

    Body parameters

    The following query string parameters are required in the URL:

    ParameterTypeDescription
    startTsNumberThe start point (Unix timestamp) of the time frame to query.
    endTsNumberThe end point (Unix timestamp) of the time frame to query.
    metricStringThe metrics you want to query. You can set it to one of the following:
  • joinSuccessRate: The rate at which users attempting to join any channel succeed, which equals Number of users who have joined ÷ Number of attempts to join.
  • joinSuccessIn5sRate: The rate at which users attempting to join any channel succeed within 5 seconds, which equals Number of users who have joined within 5 seconds ÷ Number of attempts to join.
  • audioFreezeRate: The rate at which audio freezing occurs, which equals Total audio freeze time ÷ Total audio minutes calculated by the number of streams. Only audio freezes longer than 200 milliseconds are counted.
  • videoFreezeRate: The rate at which video freezing occurs, which equals Total video freeze time ÷ Total video minutes calculated by the number of streams. Only video freezes longer than 600 milliseconds are counted.
  • networkDelay: The rate at which network delay occurs, which equals Total end-to-end network delay ÷ Total audio and video minutes calculated by the number of streams. Only end-to-end network delays longer than 400 milliseconds are counted.
  • dimensionString(Optional) The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed:
  • country: Country.
  • region: Region.
  • network: Network type.
  • sdkVersion: SDK version.
  • os: Operating system.
  • device: Device model.
  • channelSize: Size of the channel.
  • If this parameter is set, the request will return the top 20 (top 50 for device dimension) values in the corresponding dimension by default.
    When the metric is set to peakConcurrentUsers or peakConcurrentChannels, specifying dimension and dimensionValues is not supported, and the request will only return aggregated results by App ID dimension.
    dimensionValuesString(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.
    You can obtain the top values for the current dimension by not specifying dimensionValues in the first request, and then select several values from the results based on your business needs to pass as the value of dimensionValues in subsequent requests.
    When dimension is channelSize, dimensionValues is not supported. The results will be grouped based on the preset gradient scale.
    filtersJSONArray(Optional) The region filters used to filter results by country. This parameter is only valid when dimension is set to region. It is used to filter results from the region dimension to include only results that belong to the specified country. The following properties are included:
  • name: String. Only country is supported.
  • value: String. The country to be filtered, and only one country value is supported.
  • HTTP Request example

    The following examples query the audio freeze rate across all channels starting from 8:00 am on July 1, 2021 to 8:00 am on July 2, 2021:

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


    _11
    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
    _11
    Host: api.agora.io
    _11
    Accept: application/json
    _11
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
    _11
    _11
    {
    _11
    "startTs": 1625097600,
    _11
    "endTs": 1625184000,
    _11
    "metric": "audioFreezeRate",
    _11
    "dimension": "country"
    _11
    }

    Example 2: Query the audio freeze rates for SDK versions 3.6.1.1 and 4.1.1


    _12
    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
    _12
    Host: api.agora.io
    _12
    Accept: application/json
    _12
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
    _12
    _12
    {
    _12
    "startTs": 1625097600,
    _12
    "endTs": 1625184000,
    _12
    "metric": "audioFreezeRate",
    _12
    "dimension": "sdkVersion",
    _12
    "dimensionValues":["3.6.1.1","4.1.1"]
    _12
    }

    Example 3: Query the top 20 regions in China with the highest audio freeze rates and their respective audio freeze rate


    _12
    POST /beta/insight/usage/aggregation?appid=axxxxxxxxxxxxxxxxxxxx HTTP/1.1
    _12
    Host: api.agora.io
    _12
    Accept: application/json
    _12
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh
    _12
    _12
    {
    _12
    "startTs": 1625097600,
    _12
    "endTs": 1625184000,
    _12
    "metric": "audioFreezeRate",
    _12
    "dimension": "region",
    _12
    "filters": [{"name": "country", "value": "China"}]
    _12
    }

    Response parameters

    ParameterTypeDescription
    codeNumberThe status code.
    messageStringThe success or error message.
    dataJSONArray
    • If the dimension field is not filled in the request: Return the metric data of the App ID dimension.
    • If the dimension field is filled in the request: An array composed of dimensions, refUsage, and metric data.
      • refUsage: Auxiliary usage data. In each returned data group, each metric corresponds to an auxiliary usage data used to assist in determining data validity. The corresponding relationship between metric and refUsage is as follows:
        • When metric is joinSuccessRate, refUsage represents the number of attempts to join the channel.
        • When metric is joinSuccessIn5sRate, refUsage represents the number of attempts to join the channel.
        • When metric is audioFreezeRate, refUsage represents the duration of audio calls (in minutes).
        • When metric is videoFreezeRate, refUsage represents the duration of 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:00 am on July 1, 2021 and 8:00 am on July 2, 2021.


    _17
    {
    _17
    "code": 200,
    _17
    "message": "null",
    _17
    "data": [
    _17
    {
    _17
    "country": "China",
    _17
    "refUsage": 231234,
    _17
    "audioFreezeRate": 0.0017,
    _17
    },
    _17
    {
    _17
    "country": "United States",
    _17
    "refUsage": 213212,
    _17
    "audioFreezeRate": 0.0014
    _17
    }
    _17
    ......
    _17
    ]
    _17
    }

    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.


    _16
    {
    _16
    "code": 200,
    _16
    "message": "null",
    _16
    "data": [
    _16
    {
    _16
    "sdkVersion": "3.6.1.1",
    _16
    "refUsage": 231234,
    _16
    "audioFreezeRate": 0.0017,
    _16
    },
    _16
    {
    _16
    "sdkVersion": "4.1.1",
    _16
    "refUsage": 213212,
    _16
    "audioFreezeRate": 0.0014
    _16
    }
    _16
    ]
    _16
    }

    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.


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

    Real-time Monitoring

    With the Real-time Monitoring RESTful APIs, you can query the scale and quality metrics within a specified time frame. The granularity of the returned data is seconds, which can reflect the actual situation in close to real time.

    The data is returned in regular 20-second time windows starting from 00:00:00. For example, [00:00:00, 00:00:20] is a time window, while [00:00:10, 00:00:30] is not a time window.

    API limits

    The limits of the Real-time Monitoring RESTful APIs depend on the pricing plan you subscribe to.

    The Starter, Standard, Premium, and Enterprise pricing plans have the following differences in terms of API limits:

    StarterStandardPremiumEnterprise
    Request frequencyN/AN/ANo more than 3/minute and 480/dayNo more than 10/minute and 1440/day
    Available dataN/AN/AWithin the past 40 minutesWithin the past 60 minutes
    Query time frameN/AN/ANo longer than 40 minutesNo longer than 60 minutes
    Data delayN/AN/A40 seconds20 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:

    ParameterTypeDescription
    startTsNumberThe start point (Unix timestamp) of the time frame to query. The time window that startTs falls in is included in the response.
    endTsNumberThe end point (Unix timestamp) of the time frame to query. The time window that endTs falls in is not included in the response.
    appidStringThe App ID of your project.
    productTypeStringThe product for which you want to query the metrics. You can set it to:
  • Native: The Agora Video SDK for Android, iOS, macOS, and Windows.
  • WebRTC: The Agora Video SDK for Web.
  • metricStringThe metric you want to query. You can set it to one of the following options:
  • userCount: The total number of users across all in-use channels. A user joining multiple channels is counted multiple times.
  • channelCount: The total number of channels. A channel is counted once for each period between the time when the first user joins it and the time when the last user leaves it.
  • dimensionString(Optional) The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed:
  • country: Country.
  • region: Region.
  • network: Network type.
  • sdkVersion: SDK version.
  • os: Operating system.
  • device: Device model.
  • You can obtain the top values for the current dimension by querying top 20 real-time scale metrics, and then select several values from the results based on your business needs to pass as the value of dimensionValues in subsequent requests.
    dimensionValuesString(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.
    cnameString(Optional)The channel name. If you do not specify this parameter, the metric data of your entire project (rather than a specific channel) is returned.

    HTTP request example

    The following example queries the real-time number of users for SDK versions 3.6.1.1 and 4.1.1, with startTs set to 08:10:10 on September 17, 2021 and endTs set to 08:11:10 on the same day. The HTTP request is as follows:


    _4
    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
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response parameters

    The response contains the following fields:

    FieldTypeDescription
    codeNumberThe status code. 200 indicates that the request is successful.
    messageStringThe error message.
    dataJSONArrayAn array consisting of the following fields:
  • The metric field specified in the request.
  • ts: The Unix timestamp of the start point of the corresponding time window.
  • Response example

    For the previous HTTP request example, the response includes the total number of users, corresponding SDK version, and Unix timestamp of the following time windows:

    • [00:10:00, 00:10:20] on September 17, 2021
    • [00:10:20, 00:10:40] on September 17, 2021
    • [00:10:40, 00:11:00] on September 17, 2021

    _36
    {
    _36
    "code": 200,
    _36
    "message": null,
    _36
    "data": [
    _36
    {
    _36
    "userCount": 236,
    _36
    "sdk": "3.6.1.1",
    _36
    "ts": 1631837400
    _36
    },
    _36
    {
    _36
    "userCount": 82,
    _36
    "sdk": "4.1.1",
    _36
    "ts": 1631837400
    _36
    },
    _36
    {
    _36
    "userCount": 235,
    _36
    "sdk": "3.6.1.1",
    _36
    "ts": 1631837420
    _36
    },
    _36
    {
    _36
    "userCount": 85,
    _36
    "sdk": "4.1.1",
    _36
    "ts": 1631837420
    _36
    },
    _36
    {
    _36
    "userCount": 252,
    _36
    "sdk": "3.6.1.1",
    _36
    "ts": 1631837440
    _36
    },
    _36
    {
    _36
    "userCount": 90,
    _36
    "sdk": "4.1.1",
    _36
    "ts": 1631837440
    _36
    }
    _36
    ]
    _36
    }

    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:

    ParameterTypeDescription
    startTsNumberThe start point (Unix timestamp) of the time frame to query. The time window that startTs falls in is included in the response.
    endTsNumberThe end point (Unix timestamp) of the time frame to query. The time window that endTs falls in is not included in the response.
    appidStringThe App ID of your project.
    productTypeStringThe product for which you want to query the metrics. You can set it to one of the following options:
  • Native: The Agora Video SDK for Android, iOS, macOS, and Windows.
  • WebRTC: The Agora Video SDK for Web.
  • metricStringThe metrics you want to query. You can set it to one of the following options:
  • joinSuccessRate: The rate at which users attempting to join any channel succeed, which equals Number of users who have joined ÷ Number of attempts to join.
  • joinSuccessIn5sRate: The rate at which users attempting to join any channel succeed within 5 seconds, which equals Number of users who have joined within 5 seconds ÷ Number of attempts to join.
  • audioFreezeRate: The rate at which audio freezing occurs, which equals Total audio freeze time ÷ Total audio minutes calculated by the number of streams. Only audio freezes longer than 200 milliseconds are counted.
  • videoFreezeRate: The rate at which video freezing occurs, which equals Total video freeze time ÷ Total video minutes calculated by the number of streams. Only video freezes longer than 600 milliseconds are counted.
  • networkDelay: The rate at which network delay occurs, which equals Total end-to-end network delay ÷ Total audio and video minutes calculated by the number of streams. Only end-to-end network delays longer than 400 milliseconds are counted.
  • dimensionString(Optional) The dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed:
  • country: Country.
  • region: Region.
  • network: Network type.
  • sdkVersion: SDK version.
  • os: Operating system.
  • device: Device model.
  • You can obtain the top values for the current dimension by querying top 20 real-time scale metics, and then select several values from the results based on your business needs to pass as the value of dimensionValues in subsequent requests.
    dimensionValuesString(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.
    cnameString(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.
    uidsString(Optional) The list of user IDs (uid). You need to separate multiple user IDs with commas (for example, uids=10001,10002,10003). You can specify a maximum of 10 user IDs. The uids parameter takes effect only when you specify the cname parameter.

    HTTP request example

    The following example queries the network delay rate from 00:10:10 to 00:11:10 on September 17, 2021:

    Example 1: uids is not specified


    _4
    GET /beta/realtime/usage/by_time_20sec?startTs=1631837410&endTs=1631837470&appid=axxxxxxxxxxxxxxxxxxxx&productType=Native&metric=networkDelay HTTP/1.1
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Example 2: uids is specified as 2303692334 and 2963430861


    _4
    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
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Example 3: dimension is specified as sdkVersion, and dimensionValues as 3.6.1.1 and 4.1.1


    _4
    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
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response parameters

    The response contains the following fields:

    FieldTypeDescription
    codeNumberThe status code. 200 indicates that the request is successful.
    messageStringThe error message.
    dataJSONArray
  • 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, 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


    _18
    {
    _18
    "code": 200,
    _18
    "message": "success",
    _18
    "data": [
    _18
    {
    _18
    "networkDelay": 0.0120,
    _18
    "ts": 1631837400
    _18
    },
    _18
    {
    _18
    "networkDelay": 0.0057,
    _18
    "ts": 1631837420
    _18
    },
    _18
    {
    _18
    "networkDelay": 0.0039,
    _18
    "ts": 1631837440
    _18
    }
    _18
    ]
    _18
    }

    Example 2: uids is specified as 2303692334 and 2963430861


    _40
    {
    _40
    "code": 200,
    _40
    "message": "success",
    _40
    "data": [
    _40
    {
    _40
    "uid": 2303692334,
    _40
    "values": [
    _40
    {
    _40
    "ts": 1631837400,
    _40
    "networkDelay": 0.389
    _40
    },
    _40
    {
    _40
    "ts": 1631837420,
    _40
    "networkDelay": 0.389
    _40
    },
    _40
    {
    _40
    "ts": 1631837440,
    _40
    "networkDelay": 0.389
    _40
    }
    _40
    ]
    _40
    },
    _40
    {
    _40
    "uid": 2963430861,
    _40
    "values": [
    _40
    {
    _40
    "ts": 1631837400,
    _40
    "networkDelay": 0.389
    _40
    },
    _40
    {
    _40
    "ts": 1631837420,
    _40
    "networkDelay": 0.389
    _40
    },
    _40
    {
    _40
    "ts": 1631837440,
    _40
    "networkDelay": 0.389
    _40
    }
    _40
    ]
    _40
    }
    _40
    ]
    _40
    }

    Example 3: dimension is specified as sdkVersion, and dimensionValues as 3.6.1.1 and 4.1.1


    _36
    {
    _36
    "code": 200,
    _36
    "message": null,
    _36
    "data": [
    _36
    {
    _36
    "networkDelay": 0.389,
    _36
    "sdk": "3.6.1.1",
    _36
    "ts": 1631837400
    _36
    },
    _36
    {
    _36
    "networkDelay": 0.411,
    _36
    "sdk": "4.1.1",
    _36
    "ts": 1631837400
    _36
    },
    _36
    {
    _36
    "networkDelay": 0.343,
    _36
    "sdk": "3.6.1.1",
    _36
    "ts": 1631837420
    _36
    },
    _36
    {
    _36
    "networkDelay": 0.363,
    _36
    "sdk": "4.1.1",
    _36
    "ts": 1631837420
    _36
    },
    _36
    {
    _36
    "networkDelay": 0.511,
    _36
    "sdk": "3.6.1.1",
    _36
    "ts": 1631837440
    _36
    },
    _36
    {
    _36
    "networkDelay": 0.436,
    _36
    "sdk": "4.1.1",
    _36
    "ts": 1631837440
    _36
    }
    _36
    ]
    _36
    }

    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:

    ParameterTypeDescription
    tsNumberThe start point (Unix timestamp) of the time frame to query. The actual query range is [ts, ts + 20s].
    appidStringThe App ID of your project.
    productTypeStringThe product for which you want to query the metrics. You can set it to:
  • Native: The Agora Video SDK for Android, iOS, macOS, and Windows.
  • WebRTC: The Agora Video SDK for Web.
  • metricStringThe 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.
    dimensionStringThe dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed:
  • country: Country.
  • region: Region.
  • network: Network type.
  • sdkVersion: SDK version.
  • os: Operating system.
  • device: Device model.
  • If this parameter is set, the request will return the top 20 (top 50 for device dimension) values in the corresponding dimension by default.
    cnameString(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.

    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:


    _4
    GET /beta/realtime/usage/dimension/top20?ts=1631837410&appid=your_app_id&productType=Native&metric=userCount&dimension=sdk HTTP/1.1
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response parameters

    The response contains the following fields:

    FieldTypeDescription
    codeNumberThe status code. 200 indicates that the request is successful.
    messageStringThe error message.
    dataJSONArrayAn array consists of dimensions, metric, and the starting and ending Unix timestamps (in seconds) of the time window.

    Response example

    The response contains 20 sets of data, each representing the top 20 call volume data for each SDK version during the time window from 08:10:10 to 08:10:30 on September 17, 2021.


    _28
    _28
    {
    _28
    "code": 200,
    _28
    "message": null,
    _28
    "data": {
    _28
    "list": [
    _28
    {
    _28
    "sdk": "3.6.1.1",
    _28
    "userCount": 236,
    _28
    "windowStartTs": 1631837410,
    _28
    "windowEndTs": 1631837430
    _28
    },
    _28
    {
    _28
    "sdk": "4.1.1",
    _28
    "userCount": 82,
    _28
    "windowStartTs": 1631837410,
    _28
    "windowEndTs": 1631837430
    _28
    },
    _28
    {
    _28
    "sdk": "2.9.1",
    _28
    "userCount": 68,
    _28
    "windowStartTs": 1631837410,
    _28
    "windowEndTs": 1631837430
    _28
    },
    _28
    ...
    _28
    ]
    _28
    }
    _28
    }

    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:

    ParameterTypeDescription
    tsNumberThe start point (Unix timestamp) of the time frame to query. The actual query range is [ts, ts + 20s].
    appidStringThe App ID of your project.
    productTypeStringThe product for which you want to query the metrics. You can set it to:
  • Native: The Agora Video SDK for Android, iOS, macOS, and Windows.
  • WebRTC: The Agora Video SDK for Web.
  • metricStringThe metrics you want to query. You can set it to one of the following options:
  • joinSuccessRate: The rate at which users attempting to join any channel succeed, which equals Number of users who have joined ÷ Number of attempts to join.
  • joinSuccessIn5sRate: The rate at which users attempting to join any channel succeed within 5 seconds, which equals Number of users who have joined within 5 seconds ÷ Number of attempts to join.
  • audioFreezeRate: The rate at which audio freezing occurs, which equals Total audio freeze time ÷ Total audio minutes calculated by the number of streams. Only audio freezes longer than 200 milliseconds are counted.
  • videoFreezeRate: The rate at which video freezing occurs, which equals Total video freeze time ÷ Total video minutes calculated by the number of streams. Only video freezes longer than 600 milliseconds are counted.
  • networkDelay: The rate at which network delay occurs, which equals Total end-to-end network delay ÷ Total audio and video minutes calculated by the number of streams. Only end-to-end network delays longer than 400 milliseconds are counted.
  • dimensionStringThe dimension to be used for aggregation. Only single-dimensional values are supported, and the following values are allowed:
  • country: Country.
  • region: Region.
  • network: Network type.
  • sdkVersion: SDK version.
  • os: Operating system.
  • device: Device model.
  • If this parameter is set, the request will return the top 20 (top 50 for device dimension) values in the corresponding dimension by default.
    cnameString(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.

    Request example

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


    _4
    GET /beta/realtime/quality/dimension/top20?ts=1671624000&appid=your_app_id&productType=Native&metric=audioFreezeRate&dimension=device&extraMetrics=userCount HTTP/1.1
    _4
    Host: api.agora.io
    _4
    Accept: application/json
    _4
    Authorization: Basic ZGJhZDMyNmFkxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWQzYTczNzg2ODdiMmNiYjRh

    Response parameters

    The response contains the following fields:

    FieldTypeDescription
    codeNumberThe status code. 200 indicates that the request is successful.
    messageStringThe error message.
    dataJSONArrayAn array consists of dimensions, metric, and the starting and ending Unix timestamps (in seconds) of the time window.

    Response example

    The response contains 50 sets of data, each representing the top 50 audio freeze rate values for each device model during the time window from 20:00:00 to 20:00:20 on December 21, 2022.


    _29
    {
    _29
    "code": 200,
    _29
    "message": null,
    _29
    "data": {
    _29
    "list": [
    _29
    {
    _29
    "audioFreezeRate": 0.050833333333333335,
    _29
    "windowStartTs": 1671624000,
    _29
    "userCount": 2,
    _29
    "device": "ldn-al00",
    _29
    "windowEndTs": 1671624020
    _29
    },
    _29
    {
    _29
    "audioFreezeRate": 0,
    _29
    "windowStartTs": 1671624000,
    _29
    "userCount": 2,
    _29
    "device": "80HH",
    _29
    "windowEndTs": 1671624020
    _29
    },
    _29
    {
    _29
    "audioFreezeRate": 0,
    _29
    "windowStartTs": 1671624000,
    _29
    "userCount": 1,
    _29
    "device": "20KNA004CD",
    _29
    "windowEndTs": 1671624020
    _29
    }
    _29
    ]
    _29
    }
    _29
    }

    References

    Status codes

    CodeDescription
    200The request is successful.
    300The API limits are exceeded (Call Search only)
    400Invalid parameters.
    401Unauthorized.
    403Wrong authorization information. The request is forbidden.
    404Wrong API invoked.
    500Unknown error.

    When 300 is returned, you might get the following error messages:

    Error messageDescriptionExamples of error fix
    qps limit errorThe limit on requests per second is exceeded.If qps limit = 10, ensure that current qps < 10
    qpd limit errorThe limit on requests per day is exceeded.If qpd limit = 10000, ensure that current qpd < 10000
    query latency limit errorThe 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 errorThe 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 errorThe 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 packageYou have no access to this service.N/A

    Metrics ID

    midDescriptionUnitExample
    20001App CPU usage.%27%
    20002System CPU usage.%15%
    20003The upstream bitrate of the audio.Kbps126 Kbps
    20004The downstream bitrate of the audio.Kbps108 Kbps
    20005The freeze time in rendering the audio.ms106.67 ms
    20006The upstream bitrate of the high-quality video stream.Kbps472 Kbps
    20007The capturing frame rate of the video.fps16 fps
    20008The upstream frame rate of the high-quality video stream.fps12 fps
    20009The downstream bitrate of the video.Kbps309 Kbps
    20010The downstream frame rate of the video.fps6 fps
    20011The freeze time in rendering the video.ms2000.50 ms
    20013Quality of Picture (QP) of the video. The lower the value, the higher the video quality.————
    20015The upstream packet loss rate of the audio.%1%
    20016The end-to-end packet loss rate of the audio.%3%
    20017The upstream packet loss rate of the video.%5%
    20018The end-to-end packet loss rate of the video.%7%
    20019The width of the received video.——360
    20020The height of the received video.——640
    20021The task scheduling delay.ms2 ms
    20022The round-trip time delay from the client to the local router.ms3 ms
    20023The upstream frame rate of the low-quality video stream.fps108 fps
    20024The upstream bitrate of the low-quality video stream.Kbps126 Kbps
    20025The sampling volume of the sent audio.dB105 dB
    20026The playback volume of the received audio.dB98 dB
    20027The width of the sent video.——360
    20028The height of the sent video.——640
    vundefined