> ## 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 查询指定会话的用量明细。每条明细附带用量发生时成员的直属部门。

## 所需权限 {#hJnQQX6cs}

`statistics:read`

## 请求说明 {#hZ87Pv557}

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

## 注意事项 {#hz1w4hJnT}


* 本接口返回与指定 Session ID 匹配的 TRAE 内置模型和企业自定义模型的用量明细。模型来源以响应中的 `model_source` 字段为准。
* 单次请求最多支持传入 100 个 Session ID。系统会自动去除重复的 Session ID。

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

### 请求头参数 {#请求头参数}

<!-- @cols-width: 172,122,596 -->
| **Header 参数**  | **是否必填**  | **描述**  |
| --- | --- | --- |
| `Authorization`  | 是  | 固定取值为 `Bearer {access_token}`。关于如何获取访问令牌，参考[鉴权](enterprise_authentication)。  |
| `Content-Type`  | 是  | 固定取值为 `application/json`。  |

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

<!-- @cols-width: 142,146,115,100,407 -->
| **参数**  | **类型**  | **是否必填**  | **默认值**  | **描述**  |
| --- | --- | --- | --- | --- |
| `session_ids`  | string[]  | 是  | \-  | 待查询用量明细的会话 ID。 | \
| | | | | | \
| | | | | 如需获取会话 ID，可登录 TRAE 企业版控制台，并前往 **用量管理** > **用量明细** 来查看。  |

## 响应参数 {#hJ5A8yNNn}

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

<!-- @cols-width: 333,100,480 -->
| **参数**  | **类型**  | **描述**  |
| --- | --- | --- |
| `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`：TraeCode | \
| | | * `plugin`：TraeCode Plugin | \
| | | * `cli`：TraeCode CLI | \
| | | * `solo_desktop_code`：TraeWork 桌面版的 Code 模式 | \
| | | * `solo_desktop_work`：TraeWork 桌面版的 Work 模式 | \
| | | * `solo_web_code`：TraeWork 网页版的 Code 模式 | \
| | | * `solo_web_work`：TraeWork 网页版的 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  | 部门的完整归属路径。 | \
| | | | \
| | | 返回查询时的当前归属路径。部门后续移动时，该值会随查询时间变化。若部门已被删除，则返回空字符串。  |

## 示例 {#示例}

### 请求示例 {#hjaGOQA6z}

```Bash
curl -X POST "${HOST}/openapi/v1/statistics/session_usage_detail" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "session_ids": [
      "6a43b324xxxxd71ed71f9e19"
    ]
  }'
```

### 响应示例 {#hHkTLXm9w}

```JSON
{
  "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": "6a43b324xxxxd71ed71f9e19",
        "usage": {
          "prompt_tokens": 8000,
          "completion_tokens": 2000,
          "total_tokens": 10000,
          "cache_creation_input_tokens": 0,
          "cache_read_input_tokens": 1000
        },
        "total_cost": "0.800000",
        "total_cost_currency": "CNY",
        "consumption_source": "mixed",
        "model_call_count": 2,
        "scene": "Chat",
        "departments": [
          {
            "department_id": "20001",
            "name": "研发一部",
            "full_path": "示例企业/研发一部"
          }
        ]
      }
    ]
  }
}
```

## 错误码 {#错误码}

若该接口的请求返回错误码，参考[错误码](/enterprise_error-codes)文档进行排查。