取得組織點數用量分布

按 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）開始有，不回填歷史。
更新頻率：即時更新。