按 Identity 查询 Usage

GET /api/v1/forward/usage/identities 按 Identity 汇总指定整小时区间内的活跃 Session 数、累计活跃时长和 Credit。

旧参数下线通知 新版接口已上线，请使用 start_at、end_at 按整小时区间查询用量。旧时间戳参数 start_time、end_time（Unix 毫秒时间戳）及按 Session 创建时间统计的旧逻辑，将于 2026 年 10 月 18 日（北京时间）下线并停止支持，下线前为兼容期。请在下线前完成迁移。兼容期内，仅使用旧时间戳参数的请求保持原行为，时长字段仍为 duration_seconds（整数秒）；新整小时区间请求改用 active_seconds（数值类型，单位为秒，不固定小数位数），不再返回 duration_seconds。两套参数不可混传，否则返回 HTTP 400。到期后，旧时间戳请求不再受支持，也不会自动转换为新整小时区间请求。新版响应不再返回 session_ids。接口 URL 保持不变。

请求头

Header	是否必填	说明
`Authorization`	是	`Bearer <PAT 或管理员 SAT>`；不支持绑定 Identity 的 SAT。

普通 PAT 查询当前用户的个人用量；管理员 SAT 查询其绑定组织和工作区的用量。

查询参数

国内、海外均使用北京时间（Asia/Shanghai，UTC+08:00）。起止参数只接受整点，格式为 YYYY-MM-DDTHH:00:00。

参数	类型	是否必填	默认值	说明
`start_at`	string	是	—	查询开始时间，包含该整点；只能传一次。
`end_at`	string	是	—	查询结束时间，不包含该整点；必须晚于开始时间，跨度最多 744 小时，只能传一次。不得晚于发起请求日期的次日 `00:00:00`（北京时间）；尚未完成计算的小时不会计入结果。
`limit`	integer	否	`20`	每页分组数，范围 1–100；分页参数均只能传一次。
`after_id`	string	否	—	向后翻页游标，传上一页的 `last_id`；与 `before_id` 互斥。
`before_id`	string	否	—	使用当前页的 `first_id` 向前翻页，与 `after_id` 互斥。
`identity_id`	string	否	—	筛选一个 Identity。
`identity_ids`	string/string[]	否	—	筛选多个 Identity，支持逗号分隔或重复 query 参数。
`template_id`	string	否	—	筛选一个 Template。
`template_ids`	string/string[]	否	—	筛选多个 Template，支持逗号分隔或重复 query 参数。

区间为 [start_at, end_at)，包含开始整点，不包含结束整点。例如，2026-09-14T09:00:00 → 2026-09-14T12:00:00 覆盖 09:00–10:00、10:00–11:00、11:00–12:00 三个小时。区间可以跨越日期，但起止时间都必须是整点，不能相同。接口返回整个区间的分组汇总，不逐小时拆分返回。

示例请求

查询 2026 年 9 月 14 日 09:00 至 12:00（北京时间，共三个小时），指定两个 Template 和两个 Identity 的用量，并按 Identity 汇总。示例中的 ID 请替换为实际资源 ID。

curl -sS --get 'https://api.qoder.com/api/v1/forward/usage/identities' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  --data-urlencode 'start_at=2026-09-14T09:00:00' \
  --data-urlencode 'end_at=2026-09-14T12:00:00' \
  --data-urlencode 'template_ids=tmpl_123,tmpl_456' \
  --data-urlencode 'identity_ids=idn_abc,idn_efg'

多个 ID 使用逗号分隔，也可以重复同名 query 参数；不要使用方括号或 JSON 数组。同一类 ID 之间是“或”的关系，两类筛选条件之间是“且”（AND）的关系：只统计当前凭证权限和查询区间内，Template 属于 tmpl_123、tmpl_456 中任意一个，且 Identity 属于 idn_abc、idn_efg 中任意一个的记录。

示例响应

HTTP 200 OK 以下数值仅用于说明响应结构，假设两个 Identity 均有匹配记录。

{
  "type": "identity_usage.list",
  "start_at": "2026-09-14T09:00:00",
  "end_at": "2026-09-14T12:00:00",
  "has_more": false,
  "first_id": "idn_abc",
  "last_id": "idn_efg",
  "data": [
    {
      "type": "identity_usage",
      "identity_id": "idn_abc",
      "session_count": 3,
      "active_seconds": 720.222,
      "credits": 3.1
    },
    {
      "type": "identity_usage",
      "identity_id": "idn_efg",
      "session_count": 2,
      "active_seconds": 480.222,
      "credits": 1.58
    }
  ]
}

筛选后按 Identity 分组汇总，每条结果的 identity_id 是一个字符串。例如，idn_abc 这一行汇总它在上述两个 Template 中的匹配记录；结果不会按 Template 与 Identity 的四种组合分别返回。分组按返回的 credits 降序排列，Credit 相同时按 ID 升序排列，再按 limit 分页。没有匹配记录的 Identity 不返回分组，也不补零；全部无匹配记录时返回 data: []、has_more: false，first_id 和 last_id 均为 null。已有分组中未采集到的 Credit 按 0 处理。

响应字段

字段	类型	说明
`type`	string	固定为 `identity_usage.list`。
`start_at`	string	请求的开始时间，格式为 `YYYY-MM-DDTHH:00:00`，包含该整点，按北京时间解释。
`end_at`	string	请求的结束时间，格式为 `YYYY-MM-DDTHH:00:00`，不包含该整点，按北京时间解释。
`has_more`	boolean	当前翻页方向是否还有结果；首次查询按向后方向判断。
`first_id`	string/null	本页第一条分组的公开 ID，可作为 `before_id` 向前翻页；空页为 `null`。
`last_id`	string/null	本页最后一条分组的公开 ID，可作为 `after_id` 向后翻页；空页为 `null`。
`data`	array	Identity 用量列表。每页最多返回 `limit` 个匹配分组；每个分组均统计整个查询区间。
`data[].type`	string	固定为 `identity_usage`。
`data[].identity_id`	string	当前行的 Identity ID。
`data[].session_count`	integer	该分组在查询窗口内有活动的 Session 去重数量。
`data[].active_seconds`	number	查询时间区间内，该分组所有会话的累计活跃时长，单位为秒。先汇总毫秒，再除以 1000 换算为秒；不固定小数位数，不额外四舍五入或截断。时长为 0 时返回 `0`。
`data[].credits`	number	分组内模型 Credit 与运行 Credit 之和，汇总后向下取整保留两位小数；未采集到的 Credit 按 0 处理。

数据更新说明

按北京时间，每小时第 05 分钟后开始计算上一小时的用量，计算完成后即可查询。例如，10:05 后开始计算 [09:00, 10:00) 的用量。查询结果只汇总请求区间内已完成计算的小时，尚未完成计算的小时不会计入，后续查询结果可能更新。数据自 北京时间 2026-09-07 22:00:00 起完整。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	—	缺少必填时间、空值或重复、格式非法、非整点、开始不早于结束、跨度超过 744 小时、结束晚于北京时间次日零点，或携带 `timezone`、`start_date`、`end_date` 参数。
400	`invalid_request_error`	—	旧时间戳参数与新整小时区间参数混传；参数值为空也视为传入。
400	`invalid_request_error`	—	新整小时区间请求的 `limit` 非法、超出 1–100、分页参数重复、`after_id`、`before_id` 混传，或游标超过 64 字节、不是有效 UTF-8、含控制字符。
400	`invalid_request_error`	—	兼容期内旧时间戳参数不符合原校验规则。
401	`authentication_error`	—	未提供有效凭证，或凭证已过期。
403	`permission_error`	—	当前凭证不具备接口所需权限。
500	`api_error`	—	服务端查询失败。

HTTP 200 表示查询成功，结果可能随后续采集而更新。

按 Identity 查询 Usage

请求头

查询参数

示例请求

示例响应

响应字段

数据更新说明

错误

相关

按 Template 查询 Usage

列出 Sessions

​请求头

​查询参数

​示例请求

​示例响应

​响应字段

​数据更新说明

​错误

​相关

按 Template 查询 Usage

列出 Sessions

请求头

查询参数

示例请求

示例响应

响应字段

数据更新说明

错误

相关