> 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/maiagent-user-guide/en/build/agent/usage.md).

# Agent Usage Analytics

View backend monitoring data to understand your users.

## How to View <a href="#how-to-view" id="how-to-view"></a>

From the left menu, go to <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">AI Assistants</mark>, click the Agent you want to inspect to open its settings page, and switch to the <mark style="color:blue;">Usage Analytics</mark> tab at the top. This page has two subtabs:

| Subtab                                              | Content                                                                                                                                                                                                                                                                                                                                                                                   | Who Can View It                                                                                                                              |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Monitoring Metrics</mark> | The same metrics and charts as the AgentOps <mark style="color:blue;">AI Assistant Monitoring</mark> dashboard (conversation count, response time, error rate, streaming performance, answer quality scores, etc.), limited to this Agent; see [Dashboard Charts](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent-ops/evaluations.md#dashboard-charts) for chart descriptions | Members whose role has the <mark style="color:blue;">AI Assistant Monitoring permission</mark>; members without it see only Usage Statistics |
| <mark style="color:blue;">Usage Statistics</mark>   | This Agent's conversation volume and token usage (described below)                                                                                                                                                                                                                                                                                                                        | Members who can view this Agent                                                                                                              |

The <mark style="color:blue;">Usage Statistics</mark> charts include:

* <mark style="color:blue;">Token Usage</mark>: One line per LLM model used by this Agent, plus a <mark style="color:blue;">Total Token Usage</mark> line, showing actual LLM consumption. Refer to the [Credits Billing System](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits.md) to estimate costs
* <mark style="color:blue;">Conversation Word Count</mark>: Also one line per LLM model, plus a <mark style="color:blue;">Total Conversation Word Count</mark> line
* Conversation count
* Message count
* Average messages per conversation
* User satisfaction rate

Above the charts, you can select a time range (today, yesterday, this week, last week, this month, last month, last 7 days, last 30 days, this quarter, last quarter, this year, last year, or a custom range) and switch the aggregation interval to <mark style="color:blue;">Hour</mark>, <mark style="color:blue;">Day</mark>, or <mark style="color:blue;">Month</mark>.

These metrics help you understand Agent usage from multiple perspectives.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-365a7f2570428c98ef11ea2ae079c88048511794%2Fagent-usage-token-per-model.png?alt=media" alt="Token Usage and Conversation Word Count charts in Usage Statistics, with a hover tooltip showing per-model values and Total Token Usage"><figcaption><p>Token Usage and Conversation Word Count charts: one line per model, plus a total line</p></figcaption></figure>

### View Token Usage by Model <a href="#token-usage-by-model" id="token-usage-by-model"></a>

Each model's line in the <mark style="color:blue;">Token Usage</mark> chart shows its total tokens (input, output, and Prompt Cache combined). <mark style="color:blue;">Total Token Usage</mark> is the sum across all models. The chart does not display a legend. Hover over any date to see that day's values for each model (formatted as “Model Name | Provider”) and the total.

{% hint style="info" %}

* If a model has tokens but no word count in the selected range (for example, a model used to parse images or files), it appears only in the <mark style="color:blue;">Token Usage</mark> chart; no zero-value line is drawn for it in the <mark style="color:blue;">Conversation Word Count</mark> chart. The reverse also applies. The total line always appears and stays at zero when there is no usage.
* When the aggregation interval is <mark style="color:blue;">Hour</mark>, the <mark style="color:blue;">Token Usage</mark> and <mark style="color:blue;">Conversation Word Count</mark> charts are hidden. Switch to <mark style="color:blue;">Day</mark> or <mark style="color:blue;">Month</mark> to view them.
  {% endhint %}

**Example scenario**: A customer service manager wants to know how many tokens each model used after testing a different model for the “Order Lookup Assistant.” She opens this Agent's <mark style="color:blue;">Usage Analytics</mark> → <mark style="color:blue;">Usage Statistics</mark>, selects the last 7 days and the <mark style="color:blue;">Day</mark> interval, and hovers over the test date in the <mark style="color:blue;">Token Usage</mark> chart. She can see each model's token count and <mark style="color:blue;">Total Token Usage</mark> without filtering the organization's usage statistics page separately.

## Statistics in Detail <a href="#statistics-details" id="statistics-details"></a>

### 1. Conversation Word Count (Words Count) <a href="#words-count" id="words-count"></a>

**Calculation:**

* **Text word count**: Counts the characters in message content
* **Image cost**: Each image is counted according to the configured image word cost
* **Total word count** = Message content word count + (Number of images × Image word cost)

**Scope:** Includes user messages and Agent replies; supports daily and monthly aggregation

***

### 2. Conversation Count (Conversations Count) <a href="#conversations-count" id="conversations-count"></a>

**Calculation:**

* The counter increases by 1 whenever a new conversation is created
* Conversation statistics are updated when the first message in the conversation is created

**When updated:** When a user starts a new conversation (the first message)

{% hint style="info" %}
“Conversation Count” here differs from “Conversation Count” in the AgentOps “AI Assistant Monitoring” dashboard: here, each conversation counts once; the dashboard counts Agent replies, so multiple reply turns in the same conversation are counted separately. See [Automatic Evaluation and Agent Monitoring](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent-ops/evaluations.md#conversation-count-definition).
{% endhint %}

**Scope:** Supports hourly, daily, and monthly aggregation

***

### 3. Message Count (Messages Count) <a href="#messages-count" id="messages-count"></a>

**Calculation:**

* The counter increases by 1 whenever a new message is created
* Includes user messages and Agent replies

**When updated:** Statistics are updated each time a message is created

**Scope:** Supports hourly, daily, and monthly aggregation

***

### 4. Average Messages per Conversation <a href="#average-messages-per-conversation" id="average-messages-per-conversation"></a>

**Formula:**

```
Average messages per conversation = Message count ÷ Conversation count (displays 0 if conversation count is 0)
```

**Meaning:**

* Shows how many messages each conversation contains on average
* Reflects the depth of interaction between users and the Agent
* Higher values indicate deeper conversations and more frequent interaction

**Scope:** Supports hourly, daily, and monthly aggregation

***

### 5. User Satisfaction Rate <a href="#user-satisfaction-rate" id="user-satisfaction-rate"></a>

**Formula:**

```
User satisfaction rate = Thumbs-up count ÷ Total feedback count (displays 0 if total feedback count is 0)
Total feedback count = Thumbs-up count + Thumbs-down count
```

**Meaning:**

* Shows the proportion of positive feedback (thumbs-up rate)
* Range: 0% \~ 100%
* Higher values indicate greater user satisfaction with Agent replies

**Feedback mechanism:**

* Users can give Agent replies a thumbs-up or thumbs-down
* Statistics support real-time updates

**When updated:** When a user gives feedback (created, updated, or deleted)

**How thumbs-up / thumbs-down feedback is counted:**

* Each reply counts as at most one piece of feedback. Changing a thumbs-up to a thumbs-down decreases the thumbs-up count by 1 and increases the thumbs-down count by 1; removing feedback subtracts it from the statistics
* Feedback is attributed to the period when the rated reply was created, rather than when the thumbs-up was given. For example, if a visitor gives a thumbs-up to yesterday's reply today, it is counted toward yesterday
* **Feedback on Web Chat greetings is excluded**: Greetings are fixed text rather than AI answers. In Web Chat, greetings have only a <mark style="color:blue;">Copy</mark> button, without thumbs-up / thumbs-down buttons. If a custom API integration or an older embed script still submits feedback for a greeting, that feedback is saved on the message but is excluded from thumbs-up counts, thumbs-down counts, and user satisfaction

{% hint style="info" %}
**Why does satisfaction have a value when there is no thumbs-up in the conversation history?** Previously, thumbs-up / thumbs-down feedback on greetings was included in satisfaction. A visitor could open Web Chat, give the greeting a thumbs-up, and leave, producing 100% satisfaction with no questions or answers in the conversation history. Greeting feedback is now excluded, so satisfaction reflects only visitors' ratings of actual replies.
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-6cda82815c0a1348a03c234ed46e428cbfaf7c75%2Fweb-chat-greeting-no-feedback.png?alt=media" alt="Web Chat conversation showing only a Copy button below the greeting, and Copy, thumbs-up, and thumbs-down buttons below the Agent&#x27;s answer"><figcaption><p>Greetings have only a Copy button; Agent answers also have thumbs-up / thumbs-down buttons</p></figcaption></figure>

**Example scenario**: A customer service manager notices that the “Order Lookup Assistant” has 100% satisfaction on a particular day and wants to confirm whether this figure comes only from visitors' feedback on the greeting. She opens this Agent's Web Chat and sees only <mark style="color:blue;">Copy</mark> beneath the greeting, with thumbs-up / thumbs-down buttons only beneath Agent answers. She then returns to <mark style="color:blue;">Usage Analytics</mark> → <mark style="color:blue;">Usage Statistics</mark> in the backend, selects the <mark style="color:blue;">Day</mark> interval, and hovers over that day in the <mark style="color:blue;">User Satisfaction Rate</mark> chart. The rate comes only from visitors' thumbs-up / thumbs-down feedback on Agent answers; greeting feedback is excluded.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1f87e409d2ad280bd69755512a5afef091a268dd%2Fusage-satisfaction-chart.png?alt=media" alt="User Satisfaction Rate chart in Usage Statistics, with a hover tooltip for 2026-10-12 showing a rate of 1"><figcaption><p>User Satisfaction Rate chart: hover over a day to see its thumbs-up rate</p></figcaption></figure>

**Scope:** Supports hourly, daily, and monthly aggregation

***

## Statistics Update Mechanism <a href="#statistics-update-mechanism" id="statistics-update-mechanism"></a>

**Real-time updates:** Relevant events (new messages, new conversations, or feedback changes) immediately trigger a statistics update

**Supported aggregation intervals:**

* **Hourly**: Suitable for real-time monitoring
* **Daily**: Suitable for daily report analysis
* **Monthly**: Suitable for monthly reports and trend analysis

## Can I Export or Schedule Reports? <a href="#export-and-reports" id="export-and-reports"></a>

Usage Analytics charts can only be viewed onscreen. There is no export button or setting for scheduled report delivery. To take data out of the platform, use the following pages with export support:

| Data Needed                                                                        | Where to Export                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage and Credits by Agent, role, member, and channel                              | Each tab in Usage Statistics supports <mark style="color:blue;">Export Excel</mark>; see [Usage Statistics](https://docs.maiagent.ai/maiagent-user-guide/en/others/usage-statistics.md)                                                                                                                                                                                                                                                                                         |
| Tools used for each question and answer, and whether execution succeeded or failed | The Tool Execution Records page has no export feature. In <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">AI Assistant Monitoring</mark>, filter the text conversation records by tool and export them. The Excel <mark style="color:blue;">Tools Used (Execution Results)</mark> column lists the results; see [Filter Conversation Records by Tool Used](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent-ops/evaluations.md#filter-by-tool) |
| AI question-and-answer records                                                     | Filter and export to Excel in <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">AI Assistant Monitoring</mark>, or use the question-and-answer records API to synchronize data periodically with an internal system; see [Get Conversation Q\&A Records](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/reply/conversation-viewer.md#export-conversation-history)                                                                   |

## Use Case: Evaluate Usage Effectiveness <a href="#use-case-effectiveness-evaluation" id="use-case-effectiveness-evaluation"></a>

Track trends in user satisfaction and interaction counts to assess whether Agent response quality meets expectations and guide improvements.


---

# 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/maiagent-user-guide/en/build/agent/usage.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.
