查詢用量彙總 | ToAPIs Documentation

GET

/api/v1/account/usage/summary

中國大陸用戶請注意: 中國大陸用戶請使用 https://toapis.cn 作為接口地址 (Base URL). 文檔示例中的 https://toapis.com 請替換為 https://toapis.cn.

驗證, 分頁及錯誤處理請參閱接入說明.

使用說明

區間最長 31 天. 明細依建立時間及 ID 倒序; 彙總依日期升序, 模型 UTF-8 位元組順序, 或 Key 的 null 桶後接數字 ID 升序. 每項僅含對應的 day, model 或 api_key_id. record_count 是記錄行數, 並非完整請求數. billing_phase 為 pre_consumed, settled, unknown, 並非任務最終帳務. trace 為原請求追蹤; 選用追蹤及上游總 token 可為 null, 不影響獨立金額與輸入輸出 token. records_mutable=true, refund_accounting=not_complete, consistency=eventual. 結算與退款可更新舊記錄, 無記錄不代表零消費. 單向同步無法保證捕捉更新.

驗證

Authorizationstring請求頭必填

使用系統存取權杖, 格式為 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 此介面不接受模型 API Key, 不需要 X-User-Id.

請求參數

fromstring查詢必填

含時區的 RFC 3339 起始時間, 包含該時刻. 與 to 成對提供.

限制: date-time.

tostring查詢必填

含時區的 RFC 3339 結束時間, 不包含該時刻, 必須晚於 from.

限制: date-time.

api_key_idstring查詢

自身模型 API Key 的十進位 ID 字串. 不屬於自己時回傳 404, 已刪除 Key 仍可篩選自身歷史用量.

限制: pattern=^[1-9][0-9]*$.

modelstring查詢

精確比對模型識別碼. 用量介面的空字串會比對空模型名稱.

限制: maxLength=255.

limitinteger查詢預設值: 50

每頁最多回傳的項目數.

限制: minimum=1; maximum=100; 預設值: 50.

cursorstring查詢

原樣傳入上一頁的 next_cursor, 保留相同篩選條件. 變更條件後重新開始.

限制: maxLength=2048.

group_bystring查詢預設值: day

依日期, 模型或 API Key 分組.

限制: day, model, api_key; 預設值: day.

timezonestring查詢預設值: UTC

僅 group_by=day 時可提供. 其他分組回傳 meta.timezone=null.

限制: UTC, Asia/Shanghai; 預設值: UTC.

請求示例

curl --request GET \
  --url 'https://toapis.com/api/v1/account/usage/summary?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&group_by=day&timezone=UTC' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://toapis.com/api/v1/account/usage/summary",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "group_by": "day",
        "timezone": "UTC"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

const url = new URL("https://toapis.com/api/v1/account/usage/summary");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "group_by": "day",
  "timezone": "UTC"
}).toString();

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

回應欄位

範例使用虛構資料, 並假設 credits_per_usd="100". 實際換算請以回應為準.

清單位於 data.items, 以 has_more 及 next_cursor 分頁. 最後一頁的游標為 null, 不回傳總數.

codeinteger

業務狀態碼, 成功時為 0.

messagestring

回應訊息, 成功時為空字串. 錯誤訊息依請求語言回傳.

dataobject

本次查詢的結果物件.

data.itemsobject[]

目前頁面的記錄清單, 空結果為 [].

data.items[].daystring

日期分組值, 僅 group_by=day 回傳, 依請求的 timezone 計算. 格式為 YYYY-MM-DD.

data.items[].modelstring

模型分組值, 僅 group_by=model 回傳.

data.items[].api_key_idstring | null

API Key 分組值, 僅 group_by=api_key 回傳. 無 Key 消費歸入 null 分組.

data.items[].record_countinteger

分組內消費記錄行數, 不保證等於完整請求次數.

data.items[].recorded_cost_usdstring

分組內目前消費記錄的 USD 合計, 並非完整退款核算後的淨支出. 以十進位字串回傳以保留精度.

data.items[].recorded_creditsstring

分組內目前消費記錄的 credits 合計. 以十進位字串回傳以保留精度.

data.items[].input_tokensinteger

分組內記錄的輸入 token 總量.

data.items[].output_tokensinteger

分組內記錄的輸出 token 總量.

data.items[].unknown_phase_record_countinteger

分組內無法確認帳務階段的記錄行數.

data.has_moreboolean

是否還有下一頁.

data.next_cursorstring | null

下一頁游標, 原樣作為 cursor 傳入並保留篩選條件. 最後一頁為 null.

data.metaobject

資料來源, 查詢範圍及資料口徑等中繼資料.

data.meta.scopestring

查詢資料的歸屬範圍, 目前為驗證帳戶自身. 固定值: "self".

data.meta.fromstring

查詢時間範圍下界, 包含該時刻. 時間格式為含時區的 RFC 3339.

data.meta.tostring

查詢時間範圍上界, 不包含該時刻. 時間格式為含時區的 RFC 3339.

data.meta.time_basisstring

時間篩選及日期分組採用消費記錄的建立時間. 固定值: "record_created_at".

data.meta.cost_basisstring

金額採用目前消費記錄行的值, 並非固定的最終帳單. 固定值: "current_consume_log_amount".

data.meta.refund_accountingstring

退款核算完整性. not_complete 表示並非完整淨支出帳本. 固定值: "not_complete".

data.meta.records_mutableboolean

記錄是否可能因結算或退款更新. 目前為 true.

data.meta.consistencystring

資料一致性類型. eventual 表示記錄可能稍後更新. 固定值: "eventual".

data.meta.consume_logging_enabledboolean

消費記錄開關是否開啟. 無記錄不代表沒有扣費.

data.meta.credits_per_usdstring

每 1 USD 對應的 credits 數量. 請以此值換算. 以十進位字串回傳以保留精度.

data.meta.group_bystring

本次彙總採用的分組維度.

data.meta.timezonestring | null

日期分組的時區. 依模型或 API Key 分組時為 null.

響應示例

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "day": "2026-11-01",
        "record_count": 2,
        "recorded_cost_usd": "0.04",
        "recorded_credits": "4",
        "input_tokens": 2000,
        "output_tokens": 400,
        "unknown_phase_record_count": 0
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "scope": "self",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z",
      "time_basis": "record_created_at",
      "cost_basis": "current_consume_log_amount",
      "refund_accounting": "not_complete",
      "records_mutable": true,
      "consistency": "eventual",
      "consume_logging_enabled": true,
      "credits_per_usd": "100",
      "group_by": "day",
      "timezone": "UTC"
    }
  }
}