取得 Agent 最近活躍度

獲取一個或多個 Agent 最近 N 分鐘的新會話數和用戶提問數，適合定時探活。一次最多查詢 50 個 Agent。

請求方式

GET

調用地址

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

調用驗證

使用帳號級 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 調用統計類接口共用該額度。
查詢結果緩存 30 秒，建議每分鐘調用一次，並把多個 Agent 合併到一次請求裡。

請求

請求示例

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity?org_id=${org_id}&agent_id=${agent_id_1},${agent_id_2}&minutes=5' \ -H 'Authorization: Basic ${BASIC_TOKEN}'

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity?org_id=${org_id}&agent_id=${agent_id_1},${agent_id_2}&minutes=5' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

此代碼塊在浮窗中顯示

请求头

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

请求参数

字段	类型	必填	描述
org_id	String	是	组织 ID.
agent_id	String	是	Agent ID，多个用英文逗号分隔，最多 50個，重複的只算一次。不支持沃克弗洛。
minutes	Integer	否	统计最近多少分钟，1 到 60，默认 5。

响应

响应示例

{ "code": 0, "message": "OK", "data": { "minutes": 5, "window_start": 1790664900000, "window_end": 1790665200000, "agents": [ { "agent_id": "65f0c2a1b4e8d93a1c7e5b21", "new_conversation_count": 3, "new_message_count": 27 } ] } }

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "minutes": 5,
        "window_start": 1790664900000,
        "window_end": 1790665200000,
        "agents": [
            {
                "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
                "new_conversation_count": 3,
                "new_message_count": 27
            }
        ]
    }
}

此代碼塊在浮窗中顯示

成功響應

字段	類型	描述
minutes	Integer	統計窗口長度（分鐘）。
window_start	Long	窗口起點（毫秒時間戳）。
window_end	Long	窗口終點（毫秒時間戳，不含）。
agents[].agent_id	String	Agent ID，順序與請求裡的 `agent_id` 一致。
agents[].new_conversation_count	Long	窗口內新建、並且已經有過對話的會話數。
agents[].new_message_count	Long	窗口內用戶發出的提問數，不含 AI 回覆。

失敗響應

字段	類型	描述
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	時間範圍無效：開始時間不早於結束時間，或超過了最大查詢範圍。

統計口徑

兩個數都要看：即時通訊渠道的會話在 60 分鐘沒有新消息之前會一直沿用同一個會話，活躍的渠道 Agent 也可能長時間沒有新會話，只看新會話數會誤判為不活躍。
統計範圍：只統計開發空間的渠道，包括 API、分享頁、網頁嵌入、氣泡組件、LiveDesk 以及各即時通訊和電話渠道；不包括開發空間裡的調試預覽，以及該 Agent 在工作空間裡的使用。
更新頻率：實時計算。