Gateway 用量與匯出

用量分頁顯示花費、請求數，以及每個請求的模型、金鑰、部門和終端使用者。整月請求可從主控台或 gateway.usage.export 匯出 CSV，不含提示詞或回覆內容。

最後更新 2026-10-28

用量分頁#

AI Gateway › 用量給工作區擁有者和管理員使用。選一段期間，需要的話再選一把金鑰。頁面會顯示花費、請求數和成功率、每日趨勢、依金鑰和依模型的花費、auto 的選擇情形，接著是每個請求：執行時間、金鑰、實際回答的模型和原因、token 數和結果。被拒絕的請求會寫出是哪個額度拒絕的。

終端使用者#

用一把金鑰服務很多人的應用程式，可以註明每個請求是替誰發的。Gateway 會把它記錄為該請求的終端使用者：

端點	欄位
`/v1/chat/completions`	`user`
`/v1/responses`	`user`
`/v1/messages`	`metadata.user_id`

只會記錄這個識別碼，請求裡的其他內容都不會因此儲存，這個欄位也照原樣轉給供應商。請用你自己系統認得的 id，例如員工編號或雜湊過的信箱，不要用姓名。沒有註明的請求，會顯示為沒有終端使用者。

標籤#

標籤替請求註明它的用途，例如團隊、功能或客戶，讓用量分頁可以依標籤拆分和篩選花費。在任何推論端點的 X-AgentLab-Metadata 標頭送一個 JSON 物件：

bash

curl https://api.agentlab.cresclab.com/v1/chat/completions \
  -H "Authorization: Bearer $AGENTLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'X-AgentLab-Metadata: {"team": "support", "feature": "summary"}' \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'

用 SDK 時送同一個標頭，例如 Python：

python

reply = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={"X-AgentLab-Metadata": '{"team": "support", "feature": "summary"}'},
)

在 /v1/chat/completions 和 /v1/responses，OpenAI 本身的 metadata 內文欄位也會當成標籤讀取，並照原樣轉給供應商。同一個請求兩者都送時會合併；兩邊都有的鍵，值必須相同。這個標頭永遠不會轉給供應商。

規則	上限
標籤	每個請求最多 16 個。
鍵	1 到 64 個英文字母、數字、`_`、`.` 或 `-`。
值	1 到 512 個字元的字串，不含控制字元。

標籤違反規則的請求會被拒絕，回 400 invalid_metadata，訊息會寫出違反的規則；標籤絕不會被悄悄丟掉。在 AI Gateway › 用量的明細選標籤，再挑一個鍵，就能看到依各個值拆分的花費；點選一個值可把整頁縮小到它。請求詳情和 CSV 匯出都會顯示每個請求的標籤。標籤和終端使用者一樣是你自己的標記：不要放個人資料或提示詞內容。

匯出一個月#

在用量分頁選擇匯出 CSV，選一個月份後下載。檔案每一列是一次請求嘗試，用 Excel 打開文字不會變亂碼，而且不含任何提示詞或回覆內容。

欄位	內容
`request_id`	請求的 id，和它的 `X-Request-Id` 標頭相同。
`attempt_id`	這一次嘗試。先經過 `auto` 判斷、或被重試過的請求，會有不只一次嘗試。
`started_at`	嘗試開始的時間，UTC（ISO 8601）。
`state`	`completed`、`failed`、`uncertain`（一直沒有回報用量）、`dispatched` 或 `prepared`。
`model`	這次嘗試送往的模型。
`decision`	為什麼是這個模型：指定模型時是 `explicit_pin`，否則是 `auto` 的判斷方式。
`input_tokens`, `output_tokens`	量到的 token 數。不知道用量時留空。
`cached_read_tokens`, `cache_write_tokens`	提示詞快取的 token 數。供應商沒有回報時留空。
`cost_usd`	以當天該模型目錄價格計算的費用。不知道用量或價格時留空。
`key_id`, `key_name`	送出這個請求的金鑰。
`departments`	嘗試開始時金鑰所歸屬的部門，以 `;` 分隔。
`end_user`	請求註明的終端使用者，沒有就留空。
`failure_code`	Gateway 有記錄時，這次嘗試沒有回答的原因，例如 `inference_allowance_exceeded`。
`tags`	請求的標籤，一個 JSON 物件，例如 `{"team":"support"}`，沒有就留空。

空白儲存格代表不知道，絕不代表零。月份以 UTC 的日曆月計算。開頭是 =、+、-、@、tab 或歸位字元的儲存格，會在前面加上 '，讓試算表顯示它而不是執行它。

用程式匯出#

同一份檔案也可以從主控台 API 的 gateway.usage.export 程序分頁取得。每次呼叫最多回傳 5,000 列，CSV 文字放在 content，另外附上 nextCursor；帶著這個 cursor 再呼叫，直到它變成 null，再依序把每一頁的 content 接起來。只有第一頁帶有位元組順序標記（BOM）和標題列。呼叫者必須是工作區擁有者或管理員。