查詢生成用量日誌

查詢目前 API Key 關聯的生成用量記錄。

GET/api/v1/generations/logs

欄位	值
Base URL	https://api.gate.ai
認證	Authorization: Bearer <API_KEY>
格式	Gate.AI REST JSON
限流	每個 API Key 每秒 1 次請求

支援依 trace_id 查詢該 Trace 下的全部記錄，或查詢目前 API Key 最近 100 筆記錄。

依 Trace 查詢：請求主體包含合法 trace_id ，回傳全部屬於目前 API Key 且 Trace 精確匹配的記錄，依 id DESC 排序。
查詢最近記錄：不傳送請求主體、傳送空請求主體或傳送 {} ，回傳目前 API Key 最近 100 筆記錄，依 created_at DESC, id DESC 排序。
Trace 不存在、日誌尚未生成或不屬於目前 API Key 時，回傳 HTTP 200 和空陣列。

請求參數

名稱	位置	類型	必填	說明
Authorization	header	string	是	API Key 鑑權，格式：Bearer <API_KEY>
Content-Type	header	string	是	固定為 application/json

請求主體

名稱	類型	必填	說明
trace_id	string	否	精確查詢指定 Trace，區分大小寫，長度為 1～128 個字元。

範例：依 Trace 查詢

bash

1curl -X POST 'https://api.gate.ai/api/v1/generations/logs' \2  -H 'Authorization: Bearer <API_KEY>' \3  -H 'Content-Type: application/json' \4  -d '{"trace_id":"Trace-AbC-123"}'

範例：查詢最近 100 筆

bash

1curl -X POST 'https://api.gate.ai/api/v1/generations/logs' \2  -H 'Authorization: Bearer <API_KEY>' \3  -H 'Content-Type: application/json' \4  -d '{}'

返回欄位說明

名稱	類型	說明
code	integer	業務狀態碼，成功固定為 200。
msg	string	狀態描述，成功固定為 success。
timestamp	string	伺服器目前的 Unix 秒時間戳記。
data	array	用量日誌陣列；無匹配記錄時為[]。
data[].id	integer	用量記錄 ID。
data[].trace_id	string	請求 Trace ID。
data[].span_id	string	請求 Span ID。
data[].session_id	string	工作階段 ID。
data[].api_key_id	string	產生該記錄的 API Key ID。
data[].user_id	string	使用者 ID。
data[].app	string	呼叫應用程式識別碼。
data[].standard_model	string	標準模型名稱。
data[].usage_model	string	實際用於計量的模型名稱。
data[].stream	boolean	原請求是否使用串流回應。
data[].response_status	integer	原請求 HTTP 回應狀態碼。
data[].latency	integer	原請求耗時，單位為毫秒。
data[].input_tokens	integer	輸入 Token 數。
data[].output_tokens	integer	輸出 Token 數。
data[].total_tokens	integer	Token 總數。
data[].cache_read_tokens	integer	快取讀取 Token 數。
data[].cache_write_tokens	integer	快取寫入 Token 數。
data[].input_tokens_details	string	輸入 Token 明細，保留儲存時的字串格式。
data[].output_tokens_details	string	輸出 Token 明細，保留儲存時的字串格式。
data[].input_cost	string	輸入費用，十進位字串。
data[].output_cost	string	輸出費用，十進位字串。
data[].cache_read_cost	string	快取讀取費用，十進位字串。
data[].cache_write_cost	string	快取寫入費用，十進位字串。
data[].total_cost	string	總費用，十進位字串。
data[].is_free	boolean	本次呼叫是否由免費額度涵蓋。
data[].timestamp	string	用量發生時間，ISO 8601 UTC。
data[].created_at	string	記錄建立時間，ISO 8601 UTC。
data[].metadata	string	呼叫擴充資訊，保留儲存時的字串格式。

回傳範例

json

1{2  "code": 200,3  "msg": "success",4  "timestamp": "1784633852",5  "data": [6    {7      "id": 42,8      "trace_id": "Trace-AbC-123",9      "span_id": "span-001",10      "session_id": "session-001",11      "api_key_id": "1001",12      "user_id": "2002",13      "app": "example-client",14      "standard_model": "openai/gpt-5",15      "usage_model": "gpt-5",16      "stream": false,17      "response_status": 200,18      "latency": 842,19      "input_tokens": 120,20      "output_tokens": 80,21      "total_tokens": 200,22      "cache_read_tokens": 20,23      "cache_write_tokens": 0,24      "input_tokens_details": "{"cached_tokens":20}",25      "output_tokens_details": "{"reasoning_tokens":10}",26      "input_cost": "0.00120000",27      "output_cost": "0.00160000",28      "cache_read_cost": "0.00002000",29      "cache_write_cost": "0.00000000",30      "total_cost": "0.00282000",31      "is_free": false,32      "timestamp": "2026-07-21T08:30:00Z",33      "created_at": "2026-07-21T08:30:01Z",34      "metadata": "{"request_type":"audio"}"35    }36  ]37}

無匹配記錄

json

1{2  "code": 200,3  "msg": "success",4  "timestamp": "1784633852",5  "data": []6}

回傳結果

狀態碼	狀態碼含義	說明	資料模型
200	OK	查詢成功；無匹配記錄時 data 為空陣列。	UsageLogResponse
400	Bad Request	JSON 請求主體無效，或 trace_id 類型、長度不合法。	ErrorResponse
401	Unauthorized	API Key 缺失、無效、過期、撤銷、停用或未啟用。	ErrorResponse
403	Forbidden	預留給未來 API Key 權限策略。	ErrorResponse
429	Too Many Requests	同一 API Key 超過每秒 1 次請求；回應包含 Retry-After。	ErrorResponse
500	Internal Server Error	資料庫查詢失敗或閘道內部錯誤。	ErrorResponse

錯誤回傳範例

json

1{2  "error": {3    "type": "invalid_request_error",4    "message": "invalid API key"5  }6}