對話記錄的用量與 Credits 欄位

對話記錄 API（records）回應中 usage 與 creditCosts 的欄位意義，以及依聯絡人、Agent 與期間彙總 Credits 的做法。

GET /api/v1/records/ 列出金鑰綁定成員有權限的 Agent 對話記錄，每筆記錄對應一組「使用者訊息＋Agent 回覆」。欄位型別以 API 文件 AI 助理 為準；本頁補充 schema 只標成 object 的兩個欄位。

篩選參數

參數	說明
chatbot	Agent ID，可用逗號分隔多個
startDate／endDate	日期（YYYY-MM-DD），以記錄建立時間篩選，含首尾兩天
startDatetime／endDatetime	ISO 8601 時間，需要精確到時分秒時用這組
largeLanguageModel	模型 ID，可多個
callerMember	發起對話的成員 ID，只對成員發起的對話有效
keyword	訊息內容關鍵字
hasError、hasFeedback	只列有錯誤或有回饋的記錄

列表用頁碼分頁（預設 20、上限 100），見 API 共通規範：分頁。

usage

"usage": {
  "words": {"input": 120, "output": 380, "total": 500},
  "tokens": {
    "llm": {"input": 1540, "output": 420, "total": 1960},
    "embedding": 85,
    "embeddingImage": 0,
    "reranker": 12
  },
  "llmCallBreakdown": [ … ]
}

欄位	意義
words	訊息內容的字元數：使用者訊息計入 input，Agent 回覆計入 output
tokens.llm	這次回覆所有模型呼叫加總的 Token 數（Agent 模式可能有多次呼叫）
tokens.embedding、tokens.embeddingImage	檢索時向量化查詢用掉的文字與圖片 Token
tokens.reranker	Reranker 處理的段落數
llmCallBreakdown	每一次模型呼叫的 Token 明細，Agent 模式下用來看哪一步最耗用

usage 是用量，不是費用；費用看下方的 creditCosts。

creditCosts

"creditCosts": [
  {"itemCode": "llm-claude-sonnet-4-5", "itemName": "…", "category": "llm", "unitPrice": 0.003, "credits": 5.88},
  {"itemCode": "api-tool-call", "itemName": "…", "category": "tool", "unitPrice": 1, "credits": 1}
]

• 這筆記錄扣款的所有交易，依計費項目（itemCode）加總；沒有扣款（例如平台未啟用 Credits 計費）時為 null。

• credits 是這個項目在這筆記錄扣掉的 Credits（正數），unitPrice 是扣款當下的單價快照；項目與單價的現值見 GET /api/v1/credit/items/ 與 GET /api/v1/credit/pricing-rules/。

• 同一筆記錄的 Credits 總額＝所有項目的 credits 相加；快取節省不在這裡，見用量統計。

依聯絡人與 Agent 彙總 Credits

記錄本身帶 conversation（對話 ID）與 Agent；聯絡人要從對話取得：

1. 以 chatbot 與 startDate／endDate 列出期間內的記錄，逐頁讀到 next 為 null。

2. 對每筆記錄把 creditCosts[].credits 加總，依 conversation 分組。

3. 用 GET /api/v1/conversations/{id}/ 取得各對話的 contact，再把對話的小計歸到聯絡人；同一聯絡人可能有多段對話。

日期以平台設定的時區切分，和後台 用量統計 相同；要和後台對帳時請用同一組日期與 Agent 篩選。只需要「每位成員」或「每個 Agent」的總額時，後台的用量統計已有現成報表與 Excel 匯出，不必自己彙總，見使用者手冊 用量統計。