For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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.

usage

"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

  • 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 in the user manual.

Last updated

Was this helpful?