按 Key 統計用量

GET /api/open/v1/usage/keys

請求參數

參數	位置	類型	必填	預設值	說明
start_timestamp	query	integer	否	見說明	起始時間（含），unix 秒
end_timestamp	query	integer	否	見說明	結束時間（含），unix 秒
group_by	query	string	否	key_name	分組方式：key_name 依請求發生時的 Key 名稱彙總，同名 Key 合併為一列；key_id 每個 Key 一列
key_id	query	integer	否	—	依 Key ID 篩選，正整數；多值可重複參數或用逗號分隔。傳其他使用者的 ID 只會回傳空結果
key_name	query	string	否	—	依請求發生時的 Key 名稱精確篩選；多值需重複參數，不支援逗號分隔（名稱本身可能含逗號）
p	query	integer	否	1	頁碼，取值 1–1000000
page_size	query	integer	否	10	每頁筆數，取值 1–1000
sort_by	query	string	否	total_tokens	排序欄位：key_count（僅 group_by=key_name）、prompt_tokens、completion_tokens、total_tokens、amount
order	query	string	否	desc	排序方向：asc 或 desc

時間範圍規則：

• 兩端都省略：最近 30 天。
• 只傳 start_timestamp：向後 30 天，且不超過目前時間。
• 只傳 end_timestamp：向前 30 天。
• 範圍最長 366 天。

多值參數每個最多 50 個值，超過回傳 400 invalid_request。p / page_size 顯式傳入不合法值回傳 400，詳見 分頁。

請求範例

curl "https://www.routeapi.ai/api/open/v1/usage/keys?start_timestamp=1726400000&end_timestamp=1729000000&sort_by=total_tokens&order=desc&p=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY"

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_name": "bot",
        "key_count": 2,
        "prompt_tokens": 5000,
        "completion_tokens": 1000,
        "total_tokens": 6000,
        "amount": 0.20
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

group_by=key_id 時每個 Key 一列，帶 key_id、不帶 key_count：

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_id": 12,
        "key_name": "bot",
        "prompt_tokens": 3000,
        "completion_tokens": 600,
        "total_tokens": 3600,
        "amount": 0.12
      },
      {
        "key_id": 15,
        "key_name": "bot",
        "prompt_tokens": 2000,
        "completion_tokens": 400,
        "total_tokens": 2400,
        "amount": 0.08
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

回應欄位

欄位	類型	說明
items[].key_id	integer	僅 group_by=key_id。Key ID，可用於 查詢單一 API Key 等介面；0 表示不經 API Key 的用量（如操練場）
items[].key_name	string	group_by=key_name：請求發生時的 Key 名稱。group_by=key_id：Key 的目前名稱；Key 已不存在或 key_id 為 0 時，取該 Key 在時間範圍內最近一次請求時的名稱
items[].key_count	integer	僅 group_by=key_name。該名稱下在時間範圍內有消費的不同 Key 數量
items[].prompt_tokens	integer	該列的輸入 token 總數
items[].completion_tokens	integer	該列的輸出 token 總數
items[].total_tokens	integer	輸入與輸出 token 合計
items[].amount	number	該列消耗的金額（已扣除退款），站點幣別，兩位小數
total	integer	總列數：group_by=key_name 為名稱數，group_by=key_id 為 Key 數（含 key_id 為 0 的列）
page	integer	目前頁碼
page_size	integer	實際生效的每頁筆數
start_timestamp	integer	實際生效的起始時間
end_timestamp	integer	實際生效的結束時間

錯誤

HTTP	code	情境
400	invalid_request	group_by、sort_by 或 order 取值不合法、group_by=key_id 時 sort_by=key_count、key_id 不是正整數、時間戳非數字或為負數、時間範圍不合法、分頁參數不合法，或多值參數超過 50 個值
429	—	超過按使用者的查詢頻率限制（預設 30 次/分鐘），回應主體可能為空

其他通用錯誤碼見 開放平台 API 錯誤。

說明

• Key 名稱可能重複：group_by=key_name 會把同名 Key 合併為一列，需要區分時用 group_by=key_id。不回傳任何 Key 值。
• 先按 sort_by 指定的欄位排序，取值相同時按 key_name（group_by=key_id 時按 key_id）升序，分頁順序穩定。
• 歷史記錄裡保存的是請求發生時的 Key 名稱，改名不會回溯改寫。因此 group_by=key_name 下改名前後的用量分為兩列；key_name 篩選也匹配請求時的名稱，而 group_by=key_id 回傳的是目前名稱，兩者可能不同。
• 各列 amount 之和等於 用量統計 的金額（不計四捨五入誤差）。
• 只統計消費（計費）日誌，失敗請求不計入。
• token 數為原始計數，不是百萬單位。
• 金額使用站點顯示幣別，見 查詢餘額。
• 每行 amount 獨立四捨五入，各行相加與總量可能相差 ±0.01。
• 需要匯出 Excel 時，請以相同篩選條件分頁取得本介面並彙總 items。
• 本介面與 用量統計、帳戶日誌、匯出日誌、按模型統計 共用按使用者的查詢頻率限制（預設 30 次/分鐘），見 頻率限制。