# 查询时序用量指标 (/zh-CN/api-reference/api-ref/agora-analytics/insight-usage-time)

> 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: get-beta-insight-usage-by_time
- Method: GET
- Path: /beta/insight/usage/by_time
- Endpoint: https://api.sd-rtn.com/beta/insight/usage/by_time

## Servers

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

## Authorization

This endpoint requires authentication.

- `Authorization`

## Parameters

- `startTs` (query, required, number) - 查询的时间范围起点，Unix 时间戳（秒）。响应中会包含起点所在的时间窗口。
- `endTs` (query, required, number) - 查询的时间范围终点，Unix 时间戳（秒）。响应中不会包含终点所在的时间窗口。
- `appid` (query, required, string) - 你的项目使用的 [App ID](/zh-CN/introduction/glossary#appid)。
- `metric` (query, required, string) - 要查询的指标，支持设为以下值：
- `userCount`：通话人数，一个用户 ID 在一个频道中计为一人，在多个频道中计为多人。
- `sessionCount`：通话进出人次，用户每加入一次频道计为一个通话人次。
- `channelCount`：频道数，从有用户加入频道到所有用户离开频道计为一个通话频道。
- `peakConcurrentChannels`：最大同时在线频道数。
- `peakConcurrentUsers`：最大同时在线人数。
- `totalDuration`：音视频通话时长（分钟）。
- `totalVideoDuration`：视频通话时长（分钟）。
- `totalAudioDuration`：音频通话时长（分钟）。
- `aggregateGranularity` (query, required, string) - 返回数据的粒度，支持设为以下值：
- `1d`：按天。此时返回查询时间范围内以  UTC 时间为零点起始的一整天的数据。
- `1h`：按小时。此时返回查询时间范围内 UTC 时间为整小时的数据。

## Request body

No request body.

## Responses

### 200

OK

- `code` (number) - 响应状态码。200 表示请求成功，详见[响应状态码](/zh-CN/realtime-media/usage-analytics/reference/response-code)。
- `message` (string) - 错误消息。
- `data` (array)
  - `data.items` (object)
    - `data.items.userCount` (number) - 请求的指标名称，此处示例为通话人数。
    - `data.items.ts` (number) - Unix 时间戳（秒）。

## Response examples

### 200

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