获取 Agent 转人工率

按时间区间获取某个 Agent 的会话数、转人工会话数和转人工率，口径与控制台「Agent 洞察 → 转人工率」一致。

注意：最多查询 92 天的数据；只统计开发空间的渠道，统计范围见下方「统计口径」。

请求方式

GET

调用地址

https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff

调用验证

使用账号级 DevKey / DevSecret 的 Basic 鉴权：Authorization: Basic ${BASIC_TOKEN}，其中 ${BASIC_TOKEN} 为 DevKey:DevSecret 的 Base64 编码。

调用账号必须是 org_id 对应组织的成员，并具备「用量查看」权限（组织 Owner、管理员默认具备），同时要能查看该 Agent：Agent 创建者、组织 Owner，或被授予了该 Agent（或全部 Agent）权限的成员。
请调用组织所在数据中心的地址，${endpoint} 取查询组织列表返回的 region（SG → sg、TH → th、JP → jp）。调用了其它数据中心会返回「不是该组织成员」。

调用频率

每个开发者密钥调用本接口每分钟最多 60 次。
每次调用同时计入组织套餐「统计类 API」的每分钟额度，与 Agent API Key 调用统计类接口共用该额度。
查询结果缓存 10 分钟，建议每小时调用一次。

请求

请求示例

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff?org_id=${org_id}&agent_id=${agent_id}&start_time=1788192000000&end_time=1790784000000' \ -H 'Authorization: Basic ${BASIC_TOKEN}'

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff?org_id=${org_id}&agent_id=${agent_id}&start_time=1788192000000&end_time=1790784000000' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

此代码块在浮窗中显示

请求头

字段	类型	描述
Authorization	Basic ${BASIC_TOKEN}	使用 `DevKey:DevSecret` Base64 后的 Basic Token。

请求参数

字段	类型	必填	描述
org_id	String	是	组织 ID。
agent_id	String	是	Agent ID。不支持 Workflow。
start_time	Long	是	开始时间，毫秒时间戳。按组织时区扩展到当天 0 点。
end_time	Long	是	结束时间（不含），毫秒时间戳。按组织时区取前一毫秒所在的自然日为最后一天。起止日期最多跨 92 天。

响应

响应示例

{ "code": 0, "message": "OK", "data": { "agent_id": "65f0c2a1b4e8d93a1c7e5b21", "timezone": "+08:00", "range_start_date": "2026-09-01", "range_end_date": "2026-09-29", "data_until": 1790665200000, "conversation_count": 1200, "handoff_conversation_count": 96, "handoff_rate": 0.0800 } }

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
        "timezone": "+08:00",
        "range_start_date": "2026-09-01",
        "range_end_date": "2026-09-29",
        "data_until": 1790665200000,
        "conversation_count": 1200,
        "handoff_conversation_count": 96,
        "handoff_rate": 0.0800
    }
}

此代码块在浮窗中显示

成功响应

字段	类型	描述
agent_id	String	Agent ID。
timezone	String	组织时区（UTC 偏移，如 `+08:00`），说明日期按哪个时区切分。
range_start_date	String	实际统计的起始日期 `yyyy-MM-dd`（组织时区，含）。
range_end_date	String	实际统计的结束日期 `yyyy-MM-dd`（组织时区，含）。
data_until	Long	数据统计到的时刻（毫秒时间戳）：区间里有实时计算的日期时，为实时部分的计算时刻（结果最多缓存 10 分钟）；整个区间都已完成每日统计时，为区间终点。
conversation_count	Long	区间内有过对话的会话数（按天累加）。
handoff_conversation_count	Long	其中转过人工的会话数。
handoff_rate	Number	转人工率 = `handoff_conversation_count` ÷ `conversation_count`，0 到 1，保留 4 位小数；会话数为 0 时为 `null`。

失败响应

字段	类型	描述
code	Integer	错误码。
message	String	错误详情。

错误码

HTTP 状态码为错误码的前三位，例如 40000 对应 400、40100 对应 401、403132 对应 403。

错误码	描述
40000	参数错误，如缺少必填参数、参数取值不合法。
40001	调用过于频繁：该开发者密钥超过了本接口的每分钟上限。
40008	超过组织套餐「统计类 API」的每分钟额度。
40010	接口暂时关闭，请稍后再试。
40100	没有权限：缺少用量查看权限，或无权查看该 Agent（包括 Agent 不属于该组织）。
40105	不是该组织成员，或调用了其它数据中心的地址。
40324	DevKey 或 DevSecret 错误。
40378	Agent 已删除。
403132	时间范围无效：开始时间不早于结束时间，或超过了最大查询范围。

统计口径

会话数：每天有过对话的会话数，按天累加；跨天持续对话的会话在每一天各计一次。
转人工会话数：其中转过人工的会话数。
统计范围：只统计开发空间的渠道，包括 API、分享页、网页嵌入、气泡组件、LiveDesk 以及各即时通讯和电话渠道；不包括该 Agent 发布到工作空间后在工作空间里的使用。
更新频率：已完成每日统计的日期读每日统计；当天实时计算。每日统计在组织时区零点后由统计任务生成，生成完成前，前一天也按实时计算，不会出现零点后「昨天」为 0 的情况。
实时部分的口径：按会话最近一次对话的时间计数，跨天持续对话的会话在实时部分只计一次（计在最近对话的那天），与按天累加的每日统计可能有少量出入。