> 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/en/api-integration/endpoint-behaviors/chatbot-records-usage-api.md).
# Usage and Credits Fields in Conversation Records
The meaning of usage and creditCosts fields in conversation records API (records) responses, and how to aggregate Credits by contact, Agent, and period.
`GET /api/v1/records/` lists Agent conversation records that the member bound to the API key can access. Each record corresponds to a “user message + Agent reply” pair. Field types follow the [AI assistants](https://docs.maiagent.ai/api/api-reference/ai-zhu-li) API documentation; this page expands on two fields that the schema describes only as objects.
## Filter parameters
| Parameter | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------------- |
| `chatbot` | Agent ID; multiple IDs can be comma-separated |
| `startDate`／`endDate` | Dates (`YYYY-MM-DD`); filter by record creation time, including both the start and end dates |
| `startDatetime`／`endDatetime` | ISO 8601 timestamps; use these when precision to hours, minutes, and seconds is required |
| `largeLanguageModel` | Model ID; multiple IDs are supported |
| `callerMember` | ID of the member who initiated the conversation; applies only to member-initiated conversations |
| `keyword` | Keyword in message content |
| `hasError`、`hasFeedback` | List only records with errors or feedback |
The list uses page-number pagination (20 items by default, up to 100). See [API conventions：Pagination](https://docs.maiagent.ai/api/preparation/conventions#pagination).
## `usage`
```json
"usage": {
"words": {"input": 120, "output": 380, "total": 500},
"tokens": {
"llm": {"input": 1540, "output": 420, "total": 1960},
"embedding": 85,
"embeddingImage": 0,
"reranker": 12
},
"llmCallBreakdown": [ … ]
}
```
| Field | Meaning |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `words` | Character count of message content：user messages count toward `input`, and Agent replies toward `output` |
| `tokens.llm` | Total Tokens across all model calls for this reply (Agent mode may involve multiple calls) |
| `tokens.embedding`、`tokens.embeddingImage` | Text and image Tokens used to vectorize queries during retrieval |
| `tokens.reranker` | Number of passages processed by the Reranker |
| `llmCallBreakdown` | Token details for each model call; in Agent mode, use this to identify the most resource-intensive step |
`usage` measures consumption; for costs, see `creditCosts` below.
## `creditCosts`
```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}
]
```
* All charge transactions for this record, aggregated by billing item (`itemCode`); `null` if no charges were made (for example, if Credits billing is disabled on the platform).
* `credits` is the Credits charged for this item in this record (a positive number). `unitPrice` is a snapshot of the unit price at the time of the charge; see `GET /api/v1/credit/items/` and `GET /api/v1/credit/pricing-rules/` for current items and unit prices.
* Total Credits for a record＝the sum of `credits` across all items. Cache savings are not included here; see usage statistics.
## Aggregating Credits by contact and Agent
Each record contains `conversation` (the conversation ID) and the Agent; obtain the contact from the conversation：
1. List records for the period using `chatbot` and `startDate`／`endDate`, reading every page until `next` is `null`.
2. Sum `creditCosts[].credits` for each record and group by `conversation`.
3. Use `GET /api/v1/conversations/{id}/` to obtain each conversation's `contact`, then attribute its subtotal to that contact; a contact may have multiple conversations.
Dates are divided using the platform's configured time zone, as in Usage statistics in the admin console. To reconcile with the console, use the same date range and Agent filters. If you only need totals “per member” or “per Agent,” the console's usage statistics already provide reports and Excel exports, so you do not need to aggregate them yourself. See [Usage statistics](https://docs.maiagent.ai/others/usage-statistics) in the user manual.
---
# 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/en/api-integration/endpoint-behaviors/chatbot-records-usage-api.md?ask=&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.