文档中心

数据智能体 DataAgent（私有化）

OpenAPI

按问题导出用量明细接口文档

适用对象：DataAgent OpenAPI 调用方、联调开发人员和用量核对人员。
适用版本：DataAgent 4.4.1

接口作用

本接口按用户问题导出租户内的模型用量明细，并返回一个带有效期的 Excel 下载地址。接口不会直接返回 Excel 文件流。
导出结果按用户问题汇总用量，并补充问题内容、Agent 信息以及可跳转到对应会话的 Session URL。
对于缺少问题标识的历史用量，系统会在能够确认问题归属时补充问题信息，并将该笔用量平均分配到关联问题；无法确认归属时保留汇总数据，问题标识和问题内容为空。

接口信息

项目	内容
请求方法	GET
请求路径	/dataAgent/llm/openApi/v2/control/billings/export-question-usage-details
鉴权方式	Authorization: Bearer
请求参数位置	Query String
响应格式	JSON
导出格式	.xlsx
Excel Sheet	Question usage details

请求参数

参数	类型	必填	默认值	说明
begin	string	否	当月第一天	查询开始日期，格式为 yyyy-MM-dd，包含当天。
end	string	否	当前日期	查询结束日期，格式为 yyyy-MM-dd，包含当天。
userName	string	否	全部用户	按用户名模糊匹配；去除首尾空格后长度必须为 1～128。
expireSeconds	integer	否	3600	下载地址有效期，取值范围为 60～604800 秒。

日期边界

begin 和 end 都按自然日处理，且 end 包含当天。例如 begin=2026-10-01、end=2026-10-29，实际查询范围为：

[2026-10-01 00:00:00, 2026-10-30 00:00:00)

当 begin 与计算后的结束边界不构成有效范围时，接口返回 begin 参数错误。

处理规则

聚合口径

同一问题在同一会话上下文内产生的多次模型调用会合并展示。totalTokens 为相关调用的 Token 合计，occurredAt 为该条汇总数据的起始消费时间。

用量展示规则

billingUnit	billingConsume	计量单位	totalTokens
CREDIT	本问题消耗的积分	积分	本问题的模型调用 Token 总量
TOKEN	本问题的计费 Token 消耗量	Token	本问题的模型调用 Token 总量
NONE	0	无	本问题的模型调用 Token 总量

当 billingUnit=CREDIT 时，billingConsume 按积分展示。例如原始计费值 15187 对应导出值 151.87。

历史数据兼容

部分历史记录可能缺少问题归属信息。
系统会根据可用的会话记录尽可能补全 questionId 和 questionContext。
若一条历史用量记录可对应 N 个问题，接口将输出 N 行，并把该记录的 billingConsume 和 totalTokens 平均分配到各问题。
若无法确认问题归属，接口将保留一条记录，questionId 和 questionContext 为空。

问题内容

系统会根据可用的会话记录补充用户问题正文；无法获取问题正文时，该字段为空。

Session URL

session_url 由系统根据当前部署环境生成，可直接用于打开对应会话。调用方不需要自行拼接该地址。

成功响应

成功时 HTTP 状态码为 200，data 中返回文件名和签名下载地址。

{
  "code": "llm/ok",
  "msg": {},
  "data": {
    "fileName": "question-usage-details-20261029141014.xlsx",
    "url": "https://object-storage.example.com/signed-download-url"
  },
  "JSONIFY_PRETTYPRINT_REGULAR": false
}

字段	类型	说明
code	string	成功时固定为 llm/ok。
msg	object	成功时为空对象。
data.fileName	string	生成的 Excel 文件名。
data.url	string	带有效期的 Excel 下载地址。

Excel 导出字段

字段	类型	说明
domainId	integer	租户 ID。
contextId	string	会话上下文标识，用于区分同一会话中的不同上下文。
questionId	string/null	问题唯一标识；历史数据无法确认问题归属时为空。
questionContext	string	用户问题正文；无法解析时为空。
sessionId	string	会话 ID。
session_url	string	对应会话的前端跳转地址。
agentId	string	Agent ID。
agentName	string	Agent 名称。
isNewAgent	boolean	是否为新 Agent 类型。
memberId	integer	租户成员 ID。
userName	string	用户名。
billingMode	string	计费模式，例如 public、private。
billingConsume	number	按 billingUnit 表示的计费用量；billingUnit=NONE 时为 0。
billingUnit	string	CREDIT、TOKEN 或 NONE。
totalTokens	number	模型调用的总 Token 数。
occurredAt	datetime	当前聚合分组内最早的消费时间。

错误响应

HTTP 状态码	错误码	场景
400	INVALID_ARGUMENT	日期格式或范围错误，userName 或 expireSeconds 不合法。
404	MEMBER_NOT_FOUND	指定的 userName 不属于当前租户。
422	EXPORT_ROW_LIMIT_EXCEEDED	导出行数超过系统配置上限。

{
  "code": "INVALID_ARGUMENT",
  "msg": "One or more request arguments are invalid.",
  "extra_msg": {
    "code": "INVALID_ARGUMENT",
    "message": "One or more request arguments are invalid.",
    "messageZh": "一个或多个请求参数无效。",
    "retryable": false,
    "traceId": "trace-id",
    "details": {
      "field": "begin"
    }
  },
  "data": {},
  "JSONIFY_PRETTYPRINT_REGULAR": false
}

调用样例

curl -G 'https://{DATAAGENT_HOST}/dataAgent/llm/openApi/v2/control/billings/export-question-usage-details' \
  -H 'Authorization: Bearer <OPENAPI_TOKEN>' \
  --data-urlencode 'begin=2026-10-01' \
  --data-urlencode 'end=2026-10-29' \
  --data-urlencode 'userName=admin' \
  --data-urlencode 'expireSeconds=7200'

最近更新时间：2026.10.30 10:25:55

这个页面对您有帮助吗？

有用

无用

数据智能体 DataAgent（私有化）

日期边界 #

聚合口径 #

用量展示规则 #

历史数据兼容 #