logo
开发者文档
概述开发空间工作空间API Reference最佳实践更新日志
搜索
简体中文
API Reference / 统计 API / 获取组织积分用量分布
获取组织积分用量分布
最新更新：15 天前

获取组织积分用量分布

按 Agent / Workflow 获取组织积分或 token 的占比排名，以及按天、周、月的趋势。可以只看 Agent 或只看 Workflow。

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

请求方式

GET

调用地址

https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution

调用验证

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

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

调用频率

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

请求

请求示例

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \ -H 'Authorization: Basic ${BASIC_TOKEN}'
                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \
  -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 是 结束时间（不含），毫秒时间戳。起止日期最多跨 92 天。
metric String 否 CREDITS（积分，默认）或 TOKENS。
granularity String 否 趋势的时间粒度：DAY（默认）、WEEK（周一起算）、MONTH。
agent_type String 否 AGENT 只看 Agent，WORKFLOW 只看 Workflow；不传则两类一起排名。
top_n Integer 否 趋势序列保留的条数，1 到 50，默认 50，其余合并为一行 OTHER。

响应

响应示例

{ "code": 0, "message": "OK", "data": { "timezone": "+07:00", "data_since": "2026-10-15", "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"], "total": 812.4411, "series": [ { "row_type": "ITEM", "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "total": 402.1200, "share": 49.49, "points": [130.5000, 141.0200, 130.6000] }, { "row_type": "OTHER", "agent_id": null, "name": null, "agent_type": null, "total": 410.3211, "share": 50.51, "points": [120.1000, 150.2000, 140.0211] } ], "ranking": [ { "row_type": "ITEM", "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "total": 402.1200, "share": 49.49 } ] } }
                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "timezone": "+07:00",
        "data_since": "2026-10-15",
        "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"],
        "total": 812.4411,
        "series": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49,
                "points": [130.5000, 141.0200, 130.6000]
            },
            {
                "row_type": "OTHER",
                "agent_id": null,
                "name": null,
                "agent_type": null,
                "total": 410.3211,
                "share": 50.51,
                "points": [120.1000, 150.2000, 140.0211]
            }
        ],
        "ranking": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49
            }
        ]
    }
}
此代码块在浮窗中显示

成功响应

字段 类型 描述
timezone String 组织时区（UTC 偏移，如 +07:00）。
data_since String 积分数据最早从哪一天开始有（yyyy-MM-dd），早于它的区间不完整；还没有任何数据时为 null。
buckets String[] 时间桶的起始日期，升序：按天为当天、按周为周一（yyyy-MM-dd）、按月为 yyyy-MM。points 按这个顺序对应。
total Number 区间内的总量（积分或 token，取决于 metric）。
series Object[] 趋势用的前 top_n 行，按总量从高到低，其余合并为一行 row_type = OTHER。
ranking Object[] 完整排名，最多 500 行，超出部分合并为一行 OTHER。不含 points。
series[].row_type / ranking[].row_type String ITEM 一个 Agent 或 Workflow；OTHER 合并项；UNATTRIBUTED 不归属任何 Agent 的消耗（如知识库存储、语音识别），传了 agent_type 时不返回这一行。
series[].agent_id / ranking[].agent_id String Agent 或 Workflow 的 ID；OTHER / UNATTRIBUTED 行为 null。
series[].name / ranking[].name String 名称；OTHER / UNATTRIBUTED 行为 null。
series[].agent_type / ranking[].agent_type String AGENT 或 WORKFLOW；OTHER / UNATTRIBUTED 行为 null。
series[].total / ranking[].total Number 区间总量，保留 4 位小数。
series[].share / ranking[].share Number 占区间总量的百分比，0 到 100，保留 2 位小数。
series[].points Number[] 每个时间桶的数值。

失败响应

字段 类型 描述
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 自己名下。
  • 数据起点：从功能上线日（data_since）开始有，不回填历史。
  • 更新频率：实时更新。