> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/chatbot-records-usage-api.md).

# 對話記錄的用量與 Credits 欄位

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

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

## 篩選參數 <a href="#filters" id="filters"></a>

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

列表用頁碼分頁（預設 20、上限 100），見 [API 共通規範：分頁](https://docs.maiagent.ai/api/preparation/conventions#pagination)。

## `usage` <a href="#usage" id="usage"></a>

```json
"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` <a href="#credit-costs" id="credit-costs"></a>

```json
"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 <a href="#aggregate-by-contact" id="aggregate-by-contact"></a>

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

1. 以 `chatbot` 與 `startDate`／`endDate` 列出期間內的記錄，逐頁讀到 `next` 為 `null`。
2. 對每筆記錄把 `creditCosts[].credits` 加總，依 `conversation` 分組。
3. 用 `GET /api/v1/conversations/{id}/` 取得各對話的 `contact`，再把對話的小計歸到聯絡人；同一聯絡人可能有多段對話。

日期以平台設定的時區切分，和後台 <mark style="color:blue;">用量統計</mark> 相同；要和後台對帳時請用同一組日期與 Agent 篩選。只需要「每位成員」或「每個 Agent」的總額時，後台的用量統計已有現成報表與 Excel 匯出，不必自己彙總，見使用者手冊 [用量統計](https://docs.maiagent.ai/others/usage-statistics)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/chatbot-records-usage-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.