> 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/ja/api-integration/endpoint-behaviors/chatbot-records-usage-api.md).

# 対話レコードの使用量と Credits フィールド

会話記録 API（records）のレスポンスに含まれる usage と creditCosts のフィールドの意味、および連絡先、Agent、期間別に Credits を集計する方法を説明します。

`GET /api/v1/records/` は、API キーに紐付けられたメンバーがアクセスできる Agent の会話記録を一覧表示します。各記録は「ユーザーメッセージ＋Agent の返答」の組に対応します。フィールドの型は API ドキュメントの [AI アシスタント](https://docs.maiagent.ai/api/api-reference/ai-zhu-li)に準拠します。このページでは、schema で object としか記載されていない2つのフィールドを補足します。

## フィルターパラメータ <a href="#filters" id="filters"></a>

| パラメータ                         | 説明                                              |
| ----------------------------- | ----------------------------------------------- |
| `chatbot`                     | Agent ID です。複数の 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/ja/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.