获取 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 Token。

请求参数

字段	类型	必填	描述
org_id	String	是	组织 ID。
agent_id	String	是	Agent ID，多个用英文逗号分隔，最多 50 个，重复的只算一次。不支持 Workflow。
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 在工作空间里的使用。
更新频率：实时计算。