Skip to main content
Usage

按 Identity 查询 Usage

GET /api/v1/forward/usage/identities 查询指定时间窗口内当前账号的 Identity 维度 Usage 汇总和 session 明细。

请求头

Header是否必填说明
Authorization是Bearer <PAT 或 SAT>

查询参数

参数类型是否必填默认值说明
start_timeinteger是-Unix millisecond timestamp，时间窗口开始，包含。
end_timeinteger是-Unix millisecond timestamp，时间窗口结束，不包含；必须大于 start_time，且时间跨度不超过 31 天。
identity_idstring否-按单个 Forward Identity ID 过滤。
identity_idsstring/string[]否-按多个 Forward Identity ID 过滤；支持逗号分隔或重复 query 参数。
template_idstring否-按单个 Forward Template ID 过滤。
template_idsstring/string[]否-按多个 Forward Template ID 过滤；支持逗号分隔或重复 query 参数。

示例请求

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/usage/identities?start_time=1783267200000&end_time=1784476800000&identity_id=idn_123' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

示例响应

HTTP 200 OK 
{
  "type": "identity_usage.list",
  "start_time": 1783267200000,
  "end_time": 1784476800000,
  "data": [
    {
      "type": "identity_usage",
      "identity_id": "idn_123",
      "session_count": 5,
      "duration_seconds": 420,
      "credits": 1.23,
      "session_ids": ["sess_1", "sess_2"]
    }
  ]
}

响应字段

字段类型说明
typestring固定值 identity_usage.list。
start_timeinteger请求时间窗口开始。
end_timeinteger请求时间窗口结束。
dataarrayIdentity 维度用量列表。
data[].typestring固定值 identity_usage。
data[].identity_idstringForward Identity ID。
data[].session_countintegerForward session 个数。
data[].duration_secondsintegerForward session 运行时长汇总后换算为秒。
data[].creditsnumberCredit 按 session 汇总后的消耗，返回值保留两位小数；Credit 查询不可用时为 null。
data[].session_idsstring[]当前 Identity 维度下的 Forward session ID 列表。

错误

HTTPTypeCode触发条件
400invalid_request_error-缺少 start_time / end_time，时间格式非法，end_time <= start_time，或时间跨度超过 31 天。
401authentication_errorauthentication_requiredPAT 或 SAT 无效或已过期。
500api_error-Forward session 查询或用量指标查询失败。

相关

按 Template 查询 Usage

列出 Sessions

快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考
按 Identity 查询 Usage - Qoder CN