文档中心

TRAE CN

用量管理

按成员查询用量明细

按成员返回模型调用的用量明细，每条明细附带用量发生时用户的直属部门。

所需权限

statistics:read

请求说明

请求方式：POST

请求地址：{域名}/openapi/v1/statistics/user_usage_detail

注意事项

时间跨度最长为 180 天。

user_ids 与 emails 至少传入一个。系统会分别去除重复的成员 ID 和邮箱；去重后，两个数组的元素总数不得超过 100。同一成员同时通过 ID 和邮箱传入时，仍按两个元素计数，但响应中该成员只返回一次。

部门归属在聚合与分页前计算。成员在统计周期内发生部门变更时，变更前后的用量会拆分为不同明细项。

请求参数

请求头参数

Header 参数	是否必填	描述
Authorization	是	固定取值为 Bearer {access_token}。关于如何获取访问令牌，参考鉴权。
Content-Type	是	固定取值为 application/json。

请求体参数

参数	类型	是否必填	默认值	描述
start_time	int64	是	-	查询开始时间，Unix 秒时间戳。
end_time	int64	是	-	查询结束时间，Unix 秒时间戳。
user_ids	string[]	条件必填	-	目标成员的 ID 列表。与 emails 至少传入一个。成员的 ID 可以通过 “获取成员列表” 接口获取。
emails	string[]	条件必填	-	目标成员的邮箱列表。与 user_ids 至少传入一个。成员的邮箱可以通过 “获取成员列表” 接口获取。
page	int	否	1	需返回的页数。
page_size	int	否	100	每页返回的成员数量。取值范围：[1, 500]。

响应参数

该接口独有的响应参数如下，参数位于 data 中。通用响应参数参考此文档。

参数	类型	描述
items	array	成员维度的结果列表。
items[].start_time	int64	用量记录的开始时间，Unix 秒时间戳。
items[].user_id	string	成员的 ID。
items[].email	string	成员的邮箱。
items[].account_type	int	成员的账号类型，取值： 1：全端账号 2：Work 专属账号
items[].client	string	产生用量的客户端，取值： ide：TRAE plugin：TRAE Plugin cli：TRAE CLI solo_desktop_code：TraeWork 桌面版的 Code 模式 solo_desktop_work：TraeWork 桌面版的 Work 模式 solo_desktop_design：TraeWork 桌面版的 Design 模式 solo_web_code：TraeWork 网页版的 Code 模式 solo_web_work：TraeWork 网页版的 Work 模式 solo_web_design：TraeWork 网页版的 Design 模式 solo_mobile_code：TRAE 移动端的 Code 模式 solo_mobile_work：TRAE 移动端的 Work 模式
items[].model_name	string	产生用量的模型的展示名，取值随模型配置变化。
items[].model_type	string	产生用量的模型功能类型，取值： Chat：AI 问答 CUE：代码补全
items[].model_source	string	模型来源，取值： Trae：TRAE 内置模型 Custom：企业自定义模型
items[].session_id	string	产生用量的会话的 ID。无会话信息时返回空字符串。
items[].usage	object	Token 用量明细。
items[].usage.prompt_tokens	int	输入 Token 消耗数量。
items[].usage.completion_tokens	int	输出 Token 消耗数量。
items[].usage.total_tokens	int	Token 消耗总数。
items[].usage.cache_creation_input_tokens	int	缓存创建输入 Token 数。可为 0。
items[].usage.cache_read_input_tokens	int	缓存读取输入 Token 数。可为 0。
items[].total_cost	string	折算后的实际扣费金额。返回十进制金额字符串，固定保留 6 位小数，例如 1.500000。提示：仅统计 TRAE 内置模型的金额消耗。若为企业自定义模型，返回 “-”。
items[].total_cost_currency	string	扣费金额的币种，取值： CNY：人民币 USD：美金
items[].consumption_source	string	Token 或金额的消耗来源，取值： basic：基础会话额度 pay_go：按量计费（包含加量包） mixed：基础会话额度和按量计费混合消耗 enterprise_builtin：企业自定义模型
items[].model_call_count	int	按成员聚合后的模型调用次数。
items[].scene	string	产生用量的场景，取值： Chat：AI 问答 CUE：代码补全
items[].departments	array	用量发生时，成员的直属部门。当时没有显式部门归属时，则将数据归入企业根部门；无法确定归属时为 []。
items[].departments[].department_id	string	用量发生时，成员直属部门的真实 ID。
items[].departments[].name	string	部门的名称。返回查询时的当前部门名称。部门后续改名时，该值会随查询时间变化。若部门已被删除，则返回空字符串。
items[].departments[].full_path	string	部门的完整归属路径。返回查询时的当前归属路径。部门后续移动时，该值会随查询时间变化。若部门已被删除，则返回空字符串。

示例

请求示例

curl -X POST "${HOST}/openapi/v1/statistics/user_usage_detail" \​
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \​
  -H "Content-Type: application/json" \​
  -d '{​
    "start_time": 1780000000,​
    "end_time": 1780600000,​
    "user_ids": [​
      "123456"​
    ],​
    "page": 1,​
    "page_size": 100​
  }'​

响应示例

{​
  "code": 0,​
  "message": "success",​
  "request_id": "req_xxx",​
  "data": {​
    "items": [​
      {​
        "start_time": 1780012345,​
        "user_id": "123456",​
        "email": "alice@example.com",​
        "account_type": 1,​
        "client": "ide",​
        "model_name": "model-a",​
        "model_type": "Chat",​
        "model_source": "Trae",​
        "session_id": "sess_001",​
        "usage": {​
          "prompt_tokens": 12000,​
          "completion_tokens": 3000,​
          "total_tokens": 15000,​
          "cache_creation_input_tokens": 0,​
          "cache_read_input_tokens": 2000​
        },​
        "total_cost": "1.250000",​
        "total_cost_currency": "CNY",​
        "consumption_source": "mixed",​
        "model_call_count": 3,​
        "scene": "Chat",​
        "departments": [​
          {​
            "department_id": "20001",​
            "name": "研发一部",​
            "full_path": "示例企业/研发一部"​
          }​
        ]​
      }​
    ],​
    "pagination": {​
      "page": 1,​
      "page_size": 100,​
      "total": 1,​
      "total_pages": 1​
    }​
  }​
}​

错误码

若该接口的请求返回错误码，参考错误码文档进行排查。

最近更新时间：2026.10.12 17:54:06

这个页面对您有帮助吗？

有用

无用