查詢用量明細 | ToAPIs Documentation

GET

/api/v1/account/usage/records

中國大陸用戶請注意: 中國大陸用戶請使用 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.

請求示例

curl --request GET \
  --url 'https://toapis.com/api/v1/account/usage/records?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&api_key_id=42&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

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

const url = new URL("https://toapis.com/api/v1/account/usage/records");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "api_key_id": "42",
  "limit": "20"
}).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[].idstring

消費記錄的 ID. 以十進位 ID 字串回傳.

data.items[].created_atstring | null

建立時間. 時間格式為含時區的 RFC 3339. 無法確認或不適用時為 null.

data.items[].api_key_idstring | null

關聯模型 API Key 的 ID. 無關聯時為 null.

data.items[].key_namestring | null

記錄中的 API Key 名稱. 無法確認或不適用時為 null.

data.items[].modelstring

模型識別碼.

data.items[].task_idstring | null

關聯的平台任務 ID. 無法確認或不適用時為 null.

data.items[].recorded_cost_usdstring

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

data.items[].recorded_creditsstring

目前消費記錄的消費額度, 單位為 credits. 以十進位字串回傳以保留精度.

data.items[].billing_phasestring

記錄的帳務階段, 不等同於任務最終帳務狀態. 可選值: pre_consumed, settled, unknown.

data.items[].usageobject

記錄中的輸入, 輸出及上游回報的 token 數量.

data.items[].usage.input_tokensinteger

記錄中的輸入 token 數量.

data.items[].usage.output_tokensinteger

記錄中的輸出 token 數量.

data.items[].usage.reported_total_tokensinteger | null

上游回報的總 token 數量, 無法確認時為 null, 不自行相加補齊.

data.items[].traceobject | null

原生成請求的追蹤資訊, 與本次查詢 ID 不同. 無法確認或不適用時為 null.

data.items[].trace.request_idstring | null

原生成請求的平台追蹤 ID. 無法確認或不適用時為 null.

data.items[].trace.client_request_idstring | null

原生成請求記錄的客戶端請求 ID. 無法確認或不適用時為 null.

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 數量. 請以此值換算. 以十進位字串回傳以保留精度.

響應示例

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "9001",
        "created_at": "2026-11-01T08:00:00Z",
        "api_key_id": "42",
        "key_name": "Example Key",
        "model": "example-text-model",
        "task_id": null,
        "recorded_cost_usd": "0.02",
        "recorded_credits": "2",
        "billing_phase": "settled",
        "usage": {
          "input_tokens": 1000,
          "output_tokens": 200,
          "reported_total_tokens": 1200
        },
        "trace": {
          "request_id": "request_example_01",
          "client_request_id": "client_example_01"
        }
      }
    ],
    "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"
    }
  }
}