# 查询聚合用量指标 (/zh-CN/api-reference/api-ref/agora-analytics/insight-usage-aggregation) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 获取指定时间范围内、指定维度下的聚合用量指标,包括通话人数、通话人次、频道数、同时在线频道数、同时在线人数等。 - OpenAPI: /openapi/agora-analytics/analytics-rest-api.zh-CN.yaml - Operation ID: post-beta-insight-usage-aggregation - Method: POST - Path: /beta/insight/usage/aggregation - Endpoint: https://api.sd-rtn.com/beta/insight/usage/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) - 要查询的指标,支持设为以下值: - `userCount`:通话人数,一个用户 ID 在一个频道中计为一人,在多个频道中计为多人。 - `sessionCount`:通话进出人次,用户每加入一次频道计为一个通话人次。 - `channelCount`:频道数,从有用户加入频道到所有用户离开频道计为一个通话频道。 - `peakConcurrentChannels`:最大同时在线频道数。 - `peakConcurrentUsers`:最大同时在线人数。 - `totalDuration`:音视频通话时长(分钟)。 - `totalVideoDuration`:视频通话时长(分钟)。 - `totalAudioDuration`:音频通话时长(分钟)。 - `dimension` (string) - 统计维度,仅支持单维度指定。支持设为以下值: - `country`:国家。 - `region`:地区。 - `net`:网络类型。 - `sdk`:SDK 版本。 - `os`:操作系统。 - `device`:设备型号。将默认返回维度对应 TOP 20 的值(仅当 `dimension` 为 `device` 时,将默认返回 TOP 50 的值)。 > [!CAUTION] > 当 `metric` 为 `peakConcurrentUsers` 或 `peakConcurrentChannels` 时,不支持传 `dimension` 和 `dimensionValues`,仅返回 App ID 维度的聚合结果。 - `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": "userCount", "dimension": "country" } ``` ## Responses ### 200 OK - `code` (number) - 响应状态码。200 表示请求成功,详见[响应状态码](/zh-CN/realtime-media/usage-analytics/reference/response-code)。 - `message` (string) - 错误消息。 - `data` (array) - - 请求中没有填入 `dimension` 字段:返回 App ID 维度的指标数据。 - 请求中填入了 `dimension` 字段:由维度和指标数据组成的数组。 - `data.items` (object) ## Response examples ### 200 ```json { "code": 200, "message": "null", "data": [ { "country": "China", "userCount": 42 }, { "country": "United States", "userCount": 37 } ] } ```