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 API documentation; this page expands on two fields that the schema describes only as objects.
Filter parameters
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.
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
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
All charge transactions for this record, aggregated by billing item (
itemCode);nullif no charges were made (for example, if Credits billing is disabled on the platform).creditsis the Credits charged for this item in this record (a positive number).unitPriceis a snapshot of the unit price at the time of the charge; seeGET /api/v1/credit/items/andGET /api/v1/credit/pricing-rules/for current items and unit prices.Total Credits for a record=the sum of
creditsacross 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:
List records for the period using
chatbotandstartDate/endDate, reading every page untilnextisnull.Sum
creditCosts[].creditsfor each record and group byconversation.Use
GET /api/v1/conversations/{id}/to obtain each conversation'scontact, 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 in the user manual.
Last updated
Was this helpful?