获取组织用量汇总

按时间区间获取组织的积分消耗、新会话数和用户提问数合计，并按 Agent / Workflow 分页展开。一次调用即可拿到组织下所有 Agent 的数据，不需要逐个 Agent 调用。

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

请求方式

GET

调用地址

https://api-${endpoint}.gptbots.ai/v1/org/stat/summary

调用验证

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

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

调用频率

每个开发者密钥调用本接口每分钟最多 60 次。
每次调用同时计入组织套餐「统计类 API」的每分钟额度，与 Agent API Key 调用统计类接口共用该额度。
包含今天或昨天的查询结果缓存 5 分钟，更早日期的结果缓存 1 小时，建议每 5 到 15 分钟调用一次。

请求

请求示例

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/stat/summary?org_id=${org_id}&start_time=1792425600000&end_time=1795017600000&page=1&page_size=20' \ -H 'Authorization: Basic ${BASIC_TOKEN}'

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/stat/summary?org_id=${org_id}&start_time=1792425600000&end_time=1795017600000&page=1&page_size=20' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

此代码块在浮窗中显示

请求头

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

请求参数

字段	类型	必填	描述
org_id	String	是	组织 ID。
start_time	Long	是	开始时间，毫秒时间戳。按组织时区扩展到当天 0 点。
end_time	Long	是	结束时间（不含），毫秒时间戳。按组织时区取前一毫秒所在的自然日为最后一天。起止日期最多跨 31 天。
agent_type	String	否	只展开某一类：`AGENT` 或 `WORKFLOW`；不传则两类都列出。只影响 `agents` 列表，不影响 `total`。
page	Integer	否	页码，从 1 开始，默认 1，最大 10000。
page_size	Integer	否	每页条数，默认 20，最大 100。

响应

响应示例

{ "code": 0, "message": "OK", "data": { "org_id": "65f0c2a1b4e8d93a1c7e5b20", "timezone": "+07:00", "range_start_date": "2026-10-16", "range_end_date": "2026-11-14", "data_since": "2026-10-15", "data_until": 1794614400000, "total": { "credits": 1234.5678, "unattributed_credits": 36.2011, "conversation_count": 5210, "message_count": 48213 }, "agents": { "page": 1, "page_size": 20, "total": 86, "list": [ { "agent_id": "65f0c2a1b4e8d93a1c7e5b21", "name": "客服助手", "agent_type": "AGENT", "credits": 402.1200, "conversation_count": 2104, "message_count": 19820 }, { "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "credits": 130.5000, "conversation_count": null, "message_count": null } ] } } }

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "org_id": "65f0c2a1b4e8d93a1c7e5b20",
        "timezone": "+07:00",
        "range_start_date": "2026-10-16",
        "range_end_date": "2026-11-14",
        "data_since": "2026-10-15",
        "data_until": 1794614400000,
        "total": {
            "credits": 1234.5678,
            "unattributed_credits": 36.2011,
            "conversation_count": 5210,
            "message_count": 48213
        },
        "agents": {
            "page": 1,
            "page_size": 20,
            "total": 86,
            "list": [
                {
                    "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
                    "name": "客服助手",
                    "agent_type": "AGENT",
                    "credits": 402.1200,
                    "conversation_count": 2104,
                    "message_count": 19820
                },
                {
                    "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                    "name": "订单查询",
                    "agent_type": "WORKFLOW",
                    "credits": 130.5000,
                    "conversation_count": null,
                    "message_count": null
                }
            ]
        }
    }
}

此代码块在浮窗中显示

成功响应

字段	类型	描述
org_id	String	组织 ID。
timezone	String	组织时区（UTC 偏移，如 `+07:00`），说明日期按哪个时区切分。
range_start_date	String	实际统计的起始日期 `yyyy-MM-dd`（组织时区，含）。
range_end_date	String	实际统计的结束日期 `yyyy-MM-dd`（组织时区，含）。
data_since	String	数据最早从哪一天开始完整（`yyyy-MM-dd`）：积分从功能上线日开始有，会话数和提问数从上线前 31 天开始有，取两者中较晚的那天；早于它的日期数据不完整。还没有任何数据时为 `null`。
data_until	Long	会话数和提问数已经统计到的时刻（毫秒时间戳）。积分是实时的。
total.credits	Number	组织积分消耗合计，包含 Workflow 与不归属任何 Agent 的消耗，保留 4 位小数。
total.unattributed_credits	Number	其中不归属任何 Agent 的部分（如知识库存储、语音识别），不会出现在 `agents` 列表里。
total.conversation_count	Long	区间内新建的会话数合计。
total.message_count	Long	区间内用户提问数合计，不含 AI 回复。
agents.page	Integer	当前页码。
agents.page_size	Integer	每页条数。
agents.total	Integer	区间内有数据的 Agent 与 Workflow 个数（按 `agent_type` 过滤后）。
agents.list[].agent_id	String	Agent 或 Workflow 的 ID。
agents.list[].name	String	名称。
agents.list[].agent_type	String	`AGENT` 或 `WORKFLOW`。
agents.list[].credits	Number	积分消耗。
agents.list[].conversation_count	Long	区间内新建的会话数；Workflow 为 `null`。
agents.list[].message_count	Long	区间内的用户提问数；Workflow 为 `null`。

失败响应

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

错误码

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

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

统计口径

统计范围：只统计开发空间，包括 API、分享页、网页嵌入、气泡组件、LiveDesk 以及各即时通讯和电话渠道，以及开发空间的 Workflow；不包括工作空间（GWork）的使用，也不包括已发布 Agent 在工作空间里被使用的部分。
积分：所有消耗类型（不含积分过期与订阅支付）。Workflow 的消耗记在 Workflow 自己名下，Agent 调用 Workflow 产生的消耗不计入该 Agent。积分数据从功能上线日（data_since）开始有，不回填历史。
会话数：区间内新建、并且已经有过对话的会话数，不含开发空间调试预览。Workflow 运行不产生会话；工作空间的 AI 搜索不计入。会话数和提问数从功能上线前 31 天开始有数据。
提问数：区间内用户发出的提问消息数，不含 AI 回复。
排序：agents.list 按积分从高到低排序，积分相同时按会话数排序。区间内没有任何积分、会话和提问的 Agent 不会列出。
更新频率：积分实时更新；会话数和提问数每小时整点统计一次，约有 1 小时延迟。