> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt
> Use this file to discover all available pages before exploring further.

按邮箱或 ID 查询指定成员的用量明细。

## 所需权限 {#hBCsF6FfT}

`statistics:read`

## 请求说明 {#hPPNXhUon}

* 请求方式：POST
* 请求地址：{域名}/openapi/v1/statistics/user_usage_detail

## 使用限制 {#hE4STQbHG}


* **查询人数**：单次请求最多支持查询 100 个去重后的成员。
* **时间跨度**：单次查询的时间范围最长为 180 天。

## 请求体 {#请求参数}

<!-- @cols-width: 140,100,110,565 -->
| | | | | \
|**参数** |**类型** |**是否必填** |**描述** |
|---|---|---|---|
|`emails` |string[] |条件必填 |待查询用量明细的成员的邮箱。与 `user_ids` 至少传入一个。邮箱不区分大小写。 |
|`user_ids` |string[] |条件必填 |待查询用量明细的成员的用户 ID。与 `emails` 至少传入一个。 |\
| | | | |\
| | | |如需获取成员的用户 ID，可调用 “获取成员列表” 接口，详情参考[获取成员列表](/enterprise_get-user-list)。 |
|`start_time` |int64 |是 |查询开始时间，Unix 秒时间戳。 |
|`end_time` |int64 |是 |查询结束时间，须不早于 `start_time`。 |
|`page` |int |否 |需返回的页数。若不赋值，则使用默认值 `1`。 |
|`page_size` |int |否 |每页返回的成员数量，最多 500 条。若不赋值，则使用默认值 `100`。 |

:::tip 提示
单次请求支持同时传入 `emails` 和 `user_ids` 参数。系统会根据邮箱或用户 ID 解析成员，并自动去除重复成员。去重后，单次请求最多支持查询 100 个成员。
:::

## 响应参数 {#hHOzkTqn7}

该接口独有的响应参数如下，参数位于 `data.items[]` 中。通用响应参数参考[此文档](/enterprise_general-response-schema)。

<!-- @cols-width: 273,100,469 -->
| | | | \
|**参数** |**类型** |**描述** |
|---|---|---|
|`start_time` |int64 |用量记录的开始时间，Unix 秒时间戳。 |
|`user_id` |string |成员的用户 ID。 |
|`email` |string |成员的邮箱。 |
|`client` |string |产生用量的客户端，取值： |\
| | | |\
| | |* `ide`：TRAE IDE |\
| | |* `plugin`：TRAE 插件 |\
| | |* `cli`：TRAE CLI |\
| | |* `solo_desktop_code`：TRAE Work 桌面版的 Code 模式 |\
| | |* `solo_desktop_work`：TRAE Work 桌面版的 Work 模式 |\
| | |* `solo_web_code`：TRAE Work 网页版的 Code 模式 |\
| | |* `solo_web_work`：TRAE Work 网页版的 Work 模式 |
|`model_name` |string |产生用量的模型的展示名，取值随模型配置变化。 |
|`model_type` |string |产生用量的模型功能类型，取值： |\
| | | |\
| | |* `Chat`：AI 问答 |\
| | |* `CUE`：代码补全 |
|`model_source` |string |模型来源。返回值固定为 `Trae`，表示 “TRAE 内置模型“。 |
|`session_id` |string |产生用量的会话的 ID。无会话信息时返回空字符串。 |
|`usage` |object |Token 用量明细。 |
|`usage.prompt_tokens` |int |输入 Token 消耗数量。 |
|`usage.completion_tokens` |int |输出 Token 消耗数量。 |
|`usage.total_tokens` |int |Token 消耗总数。 |
|`usage.cache_creation_input_tokens` |int |缓存创建输入 Token 数。可为 `0`。 |
|`usage.cache_read_input_tokens` |int |缓存读取输入 Token 数。可为 `0`。 |
|`total_cost` |string |折算后的实际扣费金额。返回十进制金额字符串，固定保留 6 位小数，例如 `1.500000`。 |
|`total_cost_currency` |string |扣费金额的币种，取值： |\
| | | |\
| | |* `CNY`：人民币 |\
| | |* `USD`：美金 |
|`consumption_source` |string |Token 或金额的消耗来源，取值： |\
| | | |\
| | |* `basic`：基础会话额度 |\
| | |* `pay_go`：按量计费（包含加量包） |\
| | |* `mixed`：基础会话额度和按量计费混合消耗 |
|`model_call_count` |int |按成员聚合后的模型调用次数。 |
|`scene` |string |产生用量的场景，取值： |\
| | | |\
| | |* `Chat`：AI 问答 |\
| | |* `CUE`：代码补全 |

## 请求示例 {#hxrP2QXB0}

```Bash
curl -X POST "${HOST}/openapi/v1/statistics/user_usage_detail" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["john@example.com"],
    "user_ids": ["123456789012345678"],
    "start_time": 1700000000,
    "end_time": 1700086400,
    "page": 1,
    "page_size": 100
  }'
```

## 响应示例 {#hKvPo6PLt}

```JSON
{
  "code": 0,
  "message": "success",
  "request_id": "021xxxxxxxxx",
  "data": {
    "items": [
      {
        "start_time": 1700000000,
        "user_id": "123456789012345678",
        "email": "alice@example.com",
        "client": "ide",
        "model_name": "Doubao-Seed-2.0-Code",
        "model_type": "Chat",
        "model_source": "Trae",
        "session_id": "6a43b324xxxxd71ed71f9e19",
        "usage": {
          "prompt_tokens": 11,
          "completion_tokens": 2132,
          "total_tokens": 2143,
          "cache_creation_input_tokens": 323,
          "cache_read_input_tokens": 3213
        },
        "total_cost": "2.120000",
        "total_cost_currency": "CNY",
        "consumption_source": "basic",
        "model_call_count": 1,
        "scene": "Chat"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total": 1,
      "total_pages": 1
    }
  }
}
```