取得 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}取 [查询组织列表]（/src/zh_TW/API%20參考/帳戶%20API/查詢組織列表.md）返回的 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 的情況。
實時部分的口徑：按會話最近一次對話的時間計數，跨天持續對話的會話在實時部分只計一次（計在最近對話的那天），與按天累加的每日統計可能有少量出入。