# 查询聚合质量指标 (/zh-CN/api-reference/api-ref/agora-analytics/insight-quality-aggregation)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

获取指定时间范围内、指定维度下的聚合质量指标，包括加入频道成功率、5s 加入频道成功率、音频卡顿率、视频卡顿率、网络延迟率。

- OpenAPI: /openapi/agora-analytics/analytics-rest-api.zh-CN.yaml
- Operation ID: post-beta-insight-quality-aggregation
- Method: POST
- Path: /beta/insight/quality/aggregation
- Endpoint: https://api.sd-rtn.com/beta/insight/quality/aggregation

## Servers

- https://api.sd-rtn.com

## Authorization

This endpoint requires authentication.

- `Authorization`

## Parameters

- `appid` (query, required, string) - 你的项目使用的 [App ID](/zh-CN/introduction/glossary#appid)。

## Request body

- `startTs` (number, required) - 查询的时间范围起点，Unix 时间戳（秒）。
- `endTs` (number, required) - 查询的时间范围终点，Unix 时间戳（秒）。
- `metric` (string, required) - 要查询的指标，支持设为以下值：
- `joinSuccessRate`：加入频道成功率。
- `joinSuccessIn5sRate`：5s 内加入频道成功率。
- `audioFreezeRate`：音频卡顿率。
- `videoFreezeRate`：视频卡顿率。
- `networkDelay` ：网络延迟率。
- `productType` (string, required) - 要查询的产品类型，支持设为以下值：
- `Native`：指 Android、iOS、macOS、Windows 平台的声网 RTC SDK。
- `WebRTC`：指 Web 平台的声网 RTC SDK。
- `dimension` (string) - 统计维度，仅支持单维度指定。支持设为以下值：
- `country`：国家。
- `region`：地区。
- `network`：网络类型。
- `sdkVersion`：SDK 版本。
- `os`：操作系统。
- `device`：设备型号。
设置该参数后，将默认返回对应维度中 TOP 20 的值（仅 `device` 维度返回 TOP 50 的值）。
- `dimensionValues` (string) - 统计维度的值 ，即对 `dimension` 中设定的维度指定取值，仅在传入 `dimension` 时有效。所有值必须用双引号包括，并以逗号分隔。设置该参数后，将返回 `dimensionValues` 中传入的值对应的聚合指标数据。
> [!NOTE]
> 你可以在首次请求时，通过不传 `dimensionValues` 来获取当前 `dimension` 下的 TOP 值，再根据业务需要从中选取几个值，来作为下次请求时传入 `dimensionValues` 的值。
- `filters` (array) - 地区筛选器，仅在 `dimension` 为 `region` 时生效，用于从地区维度的返回结果中筛选出属于指定国家的结果。
  - `filters.items` (object)
    - `filters.items.name` (string) - 仅支持传入 `country`。
    - `filters.items.value` (string) - 需要筛选的国家，仅支持传入一个国家值。

### Request body example

```json
{
  "startTs": 1625097600,
  "endTs": 1625184000,
  "metric": "audioFreezeRate",
  "dimension": "country",
  "productType": "Native"
}
```

## Responses

### 200

OK

- `code` (number) - 响应状态码。200 表示请求成功，详见[响应状态码](/zh-CN/realtime-media/usage-analytics/reference/response-code)。
- `message` (string) - 错误消息。
- `data` (array) - - 请求中没有填入 `dimension` 字段：返回 App ID 维度的指标数据。
- 请求中填入了 `dimension` 字段：由维度、`refUsage` 和指标数据组成的数组。
    - `refUsage`：辅助用量数据。每组返回数据中，每个 `metric` 将对应返回一个辅助用量数据，用于辅助判断数据的有效性。以下为 `metric` 和 `refUsage` 对应关系：
        - `metric` 为 `joinSuccessRate` 时，`refUsage` 表示尝试加入频道次数。
        - `metric` 为 `joinSuccessIn5sRate` 时，`refUsage` 表示尝试加入频道次数。
        - `metric` 为 `audioFreezeRate` 时，`refUsage` 表示音频通话时长（分钟）。
        - `metric` 为 `videoFreezeRate` 时，`refUsage` 表示视频通话时长（分钟）。
        - `metric` 为 `networkDelay`  时，`refUsage` 表示音视频总通话时长（分钟）。
  - `data.items` (object)

## Response examples

### 200

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