> 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/others/usage-statistics.md).

# Usage Statistics

A complete guide to the Usage Statistics page in Organization Settings, including access permissions and role-based restrictions to authorized Agents, filters, usage overview and cache savings, per-Ag

<mark style="color:blue;">Usage Statistics</mark> is the main place for administrators to review organization usage. View overall trends over a date range, rank usage by Agent, role, member, chat platform, or contact to identify the largest users, and export the results to Excel. Organizations billed in Credits can also view Credit consumption, breakdowns by billing category, and cache savings.

## Who Can Use It <a href="#permissions" id="permissions"></a>

* Your role must have <mark style="color:blue;">Usage Statistics Permission</mark> under <mark style="color:blue;">Organization Permissions</mark> (organization owners have this by default; see [Edit Role Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md#edit-role-permissions) for setup).
* The <mark style="color:blue;">Credits</mark> metric, Credit columns, and <mark style="color:blue;">Billing Categories</mark> tab appear only for organizations billed in Credits (see [Credits Billing](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits.md)).
* Roles can restrict members to viewing usage only for Agents they are authorized to access. See [View Usage for Authorized Agents Only](#scope-to-authorized-agents).

## View Usage for Authorized Agents Only <a href="#scope-to-authorized-agents" id="scope-to-authorized-agents"></a>

For roles with usage statistics permission, you can also configure the <mark style="color:blue;">Usage Statistics Scope</mark> to determine how much members can see on this page:

| Option                                                         | Data Members Can See                                                                                                                                                                                              |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Entire Organization</mark> (default) | Usage across the entire organization                                                                                                                                                                              |
| <mark style="color:blue;">Authorized Assistants Only</mark>    | Usage generated only by Agents assigned to the member's roles (see [Assign AI Assistants](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md#assign-chatbots) for how to assign Agents) |

For example, an Agent administrator in customer service manages 3 departmental Agents and needs to track their usage, while the organization wants to keep other departments' figures private. After an administrator changes the usage statistics scope of this person's role to <mark style="color:blue;">Authorized Assistants Only</mark>, a notice at the top of Usage Statistics indicates that only authorized usage is shown. Tabs such as <mark style="color:blue;">AI Assistants</mark> and <mark style="color:blue;">Members</mark> also count usage only for these 3 Agents.

### Setup Steps <a href="#scope-setup" id="scope-setup"></a>

1. In the left menu, select <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark>, then click <mark style="color:blue;">Edit Role Permissions</mark> in the <mark style="color:blue;">Management Actions</mark> section.
2. In the role list, click <mark style="color:blue;">Edit</mark> for the role you want to configure, then open the <mark style="color:blue;">Role Permissions</mark> tab.
3. Enable <mark style="color:blue;">Usage Statistics Permission</mark> under <mark style="color:blue;">Organization Permissions</mark>. <mark style="color:blue;">Usage Statistics Scope</mark> appears below the permission list.
4. Select <mark style="color:blue;">Authorized Assistants Only</mark> and click <mark style="color:blue;">Save</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9c959d9448d4149fb0b42d5a39b73a5a411e9886%2Fusage-statistics-role-scope-setting.png?alt=media" alt="Usage Statistics Scope at the bottom of the Role Permissions tab, with Authorized Assistants Only selected"><figcaption><p>After enabling usage statistics permission, set the usage statistics scope at the bottom of the Role Permissions tab</p></figcaption></figure>

Disabling <mark style="color:blue;">Usage Statistics Permission</mark> also hides this setting. Owners always see the entire organization; the owner role does not have this setting.

### The Scope Members Actually See <a href="#scope-resolution" id="scope-resolution"></a>

* **One role with organization-wide access grants organization-wide visibility**: If any of a member's roles has usage statistics permission with the scope set to <mark style="color:blue;">Entire Organization</mark>, the member sees the entire organization. Usage is restricted to authorized Agents only when all roles granting usage statistics permission are set to <mark style="color:blue;">Authorized Assistants Only</mark>.
* **Authorized Agents are combined across all roles**: Agents authorized for a member's roles are the combined set assigned through <mark style="color:blue;">Assign AI Assistants</mark> to all of that member's roles, including the default role. If the member has permission to use MaiGPT, MaiGPT usage is also included.

{% hint style="warning" %}
**Pay Attention to the Default Role**

* Every member has the default role, and Agents assigned to it are included in everyone's authorized scope. If the default role grants access to many Agents, selecting <mark style="color:blue;">Authorized Assistants Only</mark> can only narrow the scope to a limited extent.
* If the default role also has <mark style="color:blue;">Usage Statistics Permission</mark> enabled and its scope remains <mark style="color:blue;">Entire Organization</mark>, all members see the entire organization. Setting other roles to <mark style="color:blue;">Authorized Assistants Only</mark> has no effect.
  {% endhint %}

### What the Restricted View Shows <a href="#scoped-view" id="scoped-view"></a>

* A notice above <mark style="color:blue;">Usage Overview</mark> says: “Your role's usage statistics scope is set to ‘Authorized Assistants Only’. Only usage data for AI assistants accessible to your roles is currently shown.”
* The usage overview, all tabs, and <mark style="color:blue;">Export Excel</mark> include only usage for authorized Agents. Consumption not associated with an Agent, such as daily knowledge base storage charges, is excluded.
* <mark style="color:blue;">Balance</mark> on the <mark style="color:blue;">Credit Consumption</mark> card still shows the organization wallet balance. <mark style="color:blue;">Estimated Remaining</mark> displays “-”, because usage from only some Agents cannot predict how long the organization balance will last.

## How to Access It <a href="#how-to-enter" id="how-to-enter"></a>

In the left menu, select <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Usage Statistics</mark>.

## Filters <a href="#filters" id="filters"></a>

The filter bar at the top applies to the entire page:

| Filter           | Options                                                                                                                                                                                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Time granularity | <mark style="color:blue;">Hourly</mark>, <mark style="color:blue;">Daily</mark> (default), or <mark style="color:blue;">Monthly</mark>; determines the interval on the chart's horizontal axis                                                                                |
| Date range       | Defaults to the last 30 days                                                                                                                                                                                                                                                  |
| Metric           | <mark style="color:blue;">Token</mark>, <mark style="color:blue;">Characters</mark>, <mark style="color:blue;">Messages</mark>, <mark style="color:blue;">Conversations</mark>, or <mark style="color:blue;">Credits</mark>; determines which figures charts and rankings use |
| Time zone        | <mark style="color:blue;">Local Time Zone</mark> or <mark style="color:blue;">UTC Time Zone</mark>; affects only the chart's time axis display                                                                                                                                |

Click <mark style="color:blue;">Reset Filters</mark> to restore the defaults. On the <mark style="color:blue;">Voice Assistants</mark> tab, the metric menu changes to <mark style="color:blue;">STT Seconds</mark>, <mark style="color:blue;">TTS Characters</mark>, <mark style="color:blue;">Voice Model Tokens</mark>, and <mark style="color:blue;">Credits</mark>.

## Usage Overview <a href="#overview-cards" id="overview-cards"></a>

<mark style="color:blue;">Usage Overview</mark> displays totals for the selected period as cards:

| Card                                                                                                        | Contents                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Characters</mark>                                                                 | Input, output, and total character counts                                                                                                                                                                                                                  |
| TOKEN                                                                                                       | Input, output, and total Token counts                                                                                                                                                                                                                      |
| <mark style="color:blue;">Total Messages</mark> / <mark style="color:blue;">Total Conversations</mark>      | Number of messages and conversations in the selected period                                                                                                                                                                                                |
| <mark style="color:blue;">Credit Consumption</mark> (organizations billed in Credits)                       | Credit consumption, <mark style="color:blue;">Cache Savings</mark>, wallet <mark style="color:blue;">Balance</mark>, and <mark style="color:blue;">Estimated Remaining</mark> days based on average daily consumption over the period (for reference only) |
| <mark style="color:blue;">STT / TTS Usage</mark>, <mark style="color:blue;">Total Voice Model Tokens</mark> | The second row shows total STT seconds, TTS characters, and voice model Tokens for voice calls                                                                                                                                                             |

<mark style="color:blue;">Cache Savings</mark> is the net Credits saved during the selected period through Prompt caching, which the platform enables automatically. It can be positive, zero, or negative: positive values appear in green, zero in the normal color, and negative values in red with a “-”. A negative value means the extra Credits spent writing to the cache exceeded the Credits saved by reading from it. To see which Agents save Credits and which incur extra costs, see [Per-Agent Cache Savings](#chatbot-cache-savings). For how caching works, see [Prompt Cache Usage](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits.md#prompt-cache-usage).

## Tabs <a href="#tabs" id="tabs"></a>

| Tab                                                 | Contents                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Trends</mark>             | <mark style="color:blue;">Usage Trends</mark> for the selected metric: usage and cumulative usage at each point in time                                                                                                                                                                                                           |
| <mark style="color:blue;">AI Assistants</mark>      | Usage by Agent; for organizations billed in Credits, the table also has a <mark style="color:blue;">Cache Savings</mark> column. See [Per-Agent Cache Savings](#chatbot-cache-savings)                                                                                                                                            |
| <mark style="color:blue;">Roles</mark>              | Usage by role. See [How the Roles Tab Calculates Usage](#role-tab-aggregation)                                                                                                                                                                                                                                                    |
| <mark style="color:blue;">Members</mark>            | Usage by member, including <mark style="color:blue;">Member Name</mark> and <mark style="color:blue;">Member Email</mark>. Use this tab to see how much each person used                                                                                                                                                          |
| <mark style="color:blue;">Chat Platforms</mark>     | Usage by chat platform; the <mark style="color:blue;">Type</mark> column distinguishes sources such as web, internal, and API                                                                                                                                                                                                     |
| <mark style="color:blue;">Contacts</mark>           | Usage by contact, with one row per contact–Agent pair. Use this tab to look up external visitor usage                                                                                                                                                                                                                             |
| <mark style="color:blue;">Voice Assistants</mark>   | STT seconds, voice model Tokens, TTS characters, and <mark style="color:blue;">Voice Conversations</mark> for voice calls, by Agent                                                                                                                                                                                               |
| <mark style="color:blue;">Billing Categories</mark> | Appears only when the metric is <mark style="color:blue;">Credits</mark>. Lists Credit consumption by billing category, such as AI text generation and understanding models or knowledge base and vector retrieval systems. Expand a category to see consumption by provider and model, along with per-member consumption details |

Except for <mark style="color:blue;">Trends</mark> and <mark style="color:blue;">Billing Categories</mark>, each tab has three charts (time series, <mark style="color:blue;">Top 10 Rankings</mark>, and <mark style="color:blue;">Usage Share</mark>) and a detail table. Above the table, search by ID or name, or click <mark style="color:blue;">Export Excel</mark> to download data for the current tab, date range, and search criteria.

{% hint style="info" %}
Usage is accumulated by background jobs after message processing finishes, so recent conversations may take a little time to appear in the statistics. <mark style="color:blue;">Billing Categories</mark> figures come from periodic pre-aggregation and may differ slightly from real-time billing due to asynchronous deductions and decimal rounding.
{% endhint %}

## Export Contact Usage <a href="#export-contact-usage" id="export-contact-usage"></a>

A customer service supervisor wants to match contact usage to the company's internal data. On the <mark style="color:blue;">Contacts</mark> tab, she selects a date range and exports to Excel. She uses the <mark style="color:blue;">Contact Source ID</mark> and custom attribute columns in the file to identify the source and organize each contact's usage, without looking up contact data separately to combine reports.

### Download the Report <a href="#download-contact-report" id="download-contact-report"></a>

1. Open <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Usage Statistics</mark> and select a date range.
2. Switch to the <mark style="color:blue;">Contacts</mark> tab. If needed, enter a contact ID or name in the search box.
3. Click <mark style="color:blue;">Export Excel</mark>. To view Credit usage, first switch the metric to <mark style="color:blue;">Credits</mark>, then export.
4. Open the downloaded Excel file. After the existing usage columns, you will find <mark style="color:blue;">Contact Source ID</mark> and the custom attribute columns.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9e31484057ef02f9c4bb648f5d1a37d1a5f5397c%2Fusage-statistics-contact-export-toolbar.png?alt=media" alt="Contact ID or name search box and Export Excel button above the contact detail table"><figcaption><p>Search on the Contacts tab, then click Export Excel to download the report</p></figcaption></figure>

### Understanding the New Columns <a href="#contact-export-profile-columns" id="contact-export-profile-columns"></a>

* **Contact Source ID**: The contact's identifier in the source system. This differs from the MaiAgent Contact ID and is blank if not set.
* **Contact ＜Attribute Name＞**: A contact's custom attributes (Metadata), with one column per attribute, such as “Contact access\_environment”. The columns are the union of attributes across all contacts in this export, sorted by display name. If a contact does not have an attribute, that cell is blank.
* Custom attributes from pre-chat forms use the form field name when available; otherwise, the original attribute name is displayed. Form items mapped to standard contact fields such as name, Email, and phone are not duplicated as custom attribute columns.
* If different attributes share the same displayed column name, the system adds a “(Metadata)” suffix to distinguish them and preserves their respective values.

For example, if all exported contacts have an “access\_environment” attribute but only some have a “department” attribute, the report includes “Contact access\_environment” and “Contact department” columns. The “Contact department” cell is blank for contacts without department data. If a contact has a separate usage row for each of several Agents, every row includes that contact's Source ID and attributes.

{% hint style="info" %}
These columns are added to contact exports for both regular usage and Credits. They do not add columns to the on-screen contact detail table. If none of the exported contacts has custom attributes, no custom attribute columns appear.
{% endhint %}

## Column Definitions <a href="#column-definitions" id="column-definitions"></a>

| Column                                                                                                                                                     | Definition                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <mark style="color:blue;">Input Characters</mark> / <mark style="color:blue;">Output Characters</mark> / <mark style="color:blue;">Total Characters</mark> | Number of characters in message content. User messages count as input; Agent replies count as output                                                                                                                                                               |
| <mark style="color:blue;">Input Tokens</mark> / <mark style="color:blue;">Output Tokens</mark> / <mark style="color:blue;">Total Tokens</mark>             | Tokens processed by the model. Total Tokens = input + output, excluding cache                                                                                                                                                                                      |
| <mark style="color:blue;">Cache Writes</mark> / <mark style="color:blue;">Cache Reads</mark>                                                               | Tokens written to and read from the Prompt cache                                                                                                                                                                                                                   |
| <mark style="color:blue;">Cache Hit Rate</mark>                                                                                                            | Cache reads ÷ (input Tokens + cache writes + cache reads)                                                                                                                                                                                                          |
| <mark style="color:blue;">Messages</mark>                                                                                                                  | Counts 1 for each message, including both user messages and Agent replies                                                                                                                                                                                          |
| <mark style="color:blue;">Conversations</mark>                                                                                                             | Counts 1 when the first message of a new conversation appears                                                                                                                                                                                                      |
| Credits                                                                                                                                                    | Credit consumption during the selected period                                                                                                                                                                                                                      |
| <mark style="color:blue;">Transactions</mark>                                                                                                              | Number of Credit deductions. A single conversation may generate several, such as separate charges for model usage, caching, and tool calls                                                                                                                         |
| <mark style="color:blue;">Cache Savings</mark>                                                                                                             | Appears only on the <mark style="color:blue;">AI Assistants</mark> tab for organizations billed in Credits. Net Credits this Agent saved through Prompt caching during the selected period; can be negative. See [Per-Agent Cache Savings](#chatbot-cache-savings) |

When the metric is <mark style="color:blue;">Token</mark>, ranking and share charts also include cache writes and cache reads. Their figures may therefore exceed the table's <mark style="color:blue;">Total Tokens</mark>.

The totals above each tab (such as <mark style="color:blue;">Members</mark> on the Members tab and the Agent count on the Agents tab, returned as `totalMembers` and `totalChatbots` in the API) are the **distinct number of entities with usage records during the selected period**, rather than the current total number of members or Agents in the organization. For example, to find out how many people asked questions this week, set the period to this week and check the member count on the Members tab. The period includes the full days of the selected dates.

## Per-Agent Cache Savings <a href="#chatbot-cache-savings" id="chatbot-cache-savings"></a>

For organizations billed in Credits, the detail table on the <mark style="color:blue;">AI Assistants</mark> tab has an additional <mark style="color:blue;">Cache Savings</mark> column after <mark style="color:blue;">Credits</mark> and <mark style="color:blue;">Transactions</mark>. It shows the net Credits each Agent saved through Prompt caching during the selected period. The <mark style="color:blue;">Credit Consumption</mark> card above shows only the organization total; this column reveals which Agents save Credits and which incur extra costs.

For example, an organization administrator sees total <mark style="color:blue;">Cache Savings</mark> of 771.718 for October 19 and wants to know whether any Agents reduced the overall savings. They set the date range to 2026/10/19, open the <mark style="color:blue;">AI Assistants</mark> tab, and scroll the detail table right to <mark style="color:blue;">Cache Savings</mark>. One Agent saved 779.89. Another has 0 for both <mark style="color:blue;">Cache Writes</mark> and <mark style="color:blue;">Cache Reads</mark>, so its cache savings are 0. A third shows -8.17 in red, with 4,128 Tokens in <mark style="color:blue;">Cache Writes</mark> and 0 in <mark style="color:blue;">Cache Reads</mark>, meaning none of the content written to the cache that day was read by subsequent requests. The three rows sum to 771.72, differing from the card's 771.718 only in the number of decimal places displayed.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-edc17f7c2e0725c74c351f3e0cde98e041c929a7%2Fusage-statistics-cache-saved-overview.png?alt=media" alt="Usage overview with date range set to 2026/10/19 and cache savings of 771.718 on the Credit Consumption card"><figcaption><p>Usage overview: cache savings on the Credit Consumption card are the organization's total for the selected period</p></figcaption></figure>

### Steps to View <a href="#chatbot-cache-savings-steps" id="chatbot-cache-savings-steps"></a>

1. In the left menu, select <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Usage Statistics</mark>, then set the date range in the filter bar.
2. Switch to the <mark style="color:blue;">AI Assistants</mark> tab and scroll down to the detail table.
3. The table has many columns. Scroll right to the final column, <mark style="color:blue;">Cache Savings</mark>. Hover over the information icon next to the column name for an explanation of the figure.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ed7e1e3ceb59c3799c043ceb23f566df988499b0%2Fusage-statistics-chatbot-cache-saved-column.png?alt=media" alt="Right side of the AI Assistants detail table, showing Cache Writes, Cache Reads, Cache Hit Rate, Messages, Conversations, Credits, Transactions, and Cache Savings. The first row shows 779.89 in green; the second has 0 cache writes, 0 cache reads, and 0 cache savings; the third has 4,128 cache writes, 0 cache reads, and -8.17 cache savings in red"><figcaption><p>Cache Savings in the AI Assistants detail table: the third row has cache writes but no cache reads, resulting in negative savings</p></figcaption></figure>

This column is unaffected by the <mark style="color:blue;">Metric</mark> menu above and remains visible when <mark style="color:blue;">Token</mark> is selected. However, you cannot sort by clicking its header, and <mark style="color:blue;">Export Excel</mark> does not include this column.

### Understanding the Values <a href="#chatbot-cache-savings-values" id="chatbot-cache-savings-values"></a>

| Display                          | Meaning                                                                                                                                 |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Positive value in green          | Credits saved by reading the cache exceed the extra Credits spent writing to it; caching saves this Agent money                         |
| Negative value in red (with “-”) | Extra Credits spent writing to the cache exceed Credits saved by reading from it                                                        |
| 0 (normal color)                 | Net savings are 0, including no cache usage for this Agent during the selected period or a value that rounds to 0 at two decimal places |
| —                                | Cache savings data for this Agent was not retrieved; this differs from an actual 0                                                      |

Cache savings are calculated by multiplying each cache operation's Token count by the difference between the same model's regular input unit price and the cache unit price, then summing the results. Cache reads cost less than regular input, so each read saves Credits. Cache writes may cost more than regular input. If the written content is not read enough times afterward, the savings do not offset the extra cost, resulting in a negative total. For cache billing, see [Prompt Cache Usage](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits.md#prompt-cache-usage).

### Differences from the Organization Total <a href="#chatbot-cache-savings-vs-total" id="chatbot-cache-savings-vs-total"></a>

Each row uses the same calculation as <mark style="color:blue;">Cache Savings</mark> on the <mark style="color:blue;">Credit Consumption</mark> card, but their scopes differ. Adding the table rows may therefore not match the card total:

* **Deleted Agents**: They do not appear in the detail table, but their cache savings for the selected period still count toward the card total.
* **Usage statistics scope**: For members whose roles are set to <mark style="color:blue;">Authorized Assistants Only</mark>, both the table and card include only Agents they can access (see [View Usage for Authorized Agents Only](#scope-to-authorized-agents)).
* **Display precision**: The table shows two decimal places. The card abbreviates values of 1,000 or more with K or M (for example, 1,949.03 appears as 1.9K) and shows up to three decimal places for values below 1,000 (for example, 771.718).

## How the Roles Tab Calculates Usage <a href="#role-tab-aggregation" id="role-tab-aggregation"></a>

A role's usage is **the sum of the individual usage of all its current members**, rather than usage generated through that role:

* If a member belongs to multiple roles, their full usage counts toward every role. For example, if a member belongs to 3 roles and is the only person with usage during the period, all 3 roles show identical figures.
* Adding up usage across roles may therefore exceed the organization's actual total usage.
* Calculations use role membership at the time of the query. A member's usage before joining a role also counts toward it; after the member leaves the role, their usage no longer counts toward it.

## What Unknown Means <a href="#unknown-bucket" id="unknown-bucket"></a>

When the metric is <mark style="color:blue;">Credits</mark>, ranking and share charts on tabs such as <mark style="color:blue;">Members</mark> and <mark style="color:blue;">Chat Platforms</mark> may show “Unknown”. This means the Credit consumption cannot be attributed to a specific member. On the <mark style="color:blue;">Chat Platforms</mark> tab, it means consumption not associated with any chat platform, such as knowledge base storage. Common sources of “Unknown” on the <mark style="color:blue;">Members</mark> tab include:

| Source                         | Description                                                                                                                                             | Where to See Details                                    |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| External visitors              | Visitors who talk to Agents through chat platforms such as web Web Chat or LINE, rather than organization members                                       | <mark style="color:blue;">Contacts</mark> tab           |
| Deactivated or removed members | The corresponding member was no longer an active organization member when consumption occurred                                                          | —                                                       |
| System billing                 | Charges not triggered by a specific member, such as daily knowledge base storage charges or automated jobs whose initiating member cannot be identified | <mark style="color:blue;">Billing Categories</mark> tab |

## Why the Figures Differ from Quota Pages <a href="#why-differs-from-quota" id="why-differs-from-quota"></a>

<mark style="color:blue;">Quota Allocation</mark> on the <mark style="color:blue;">Credits</mark> page and <mark style="color:blue;">Credit Quota</mark> on the member account page display usage as “used / limit”. For example, `7,000.00 / 10,000.00` means 7,000 Credits used out of a 10,000-Credit limit for that quota. These figures often differ from Usage Statistics for the following reasons:

| Difference         | Usage Statistics                                                                  | Quotas                                                                                                                                                                                                                                                            |
| ------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Calculation period | Date range selected in the filter bar (last 30 days by default)                   | Accumulated since the quota took effect or was last reset                                                                                                                                                                                                         |
| Scope              | All usage attributed to the member                                                | Only consumption within the quota's [applicable scope](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/member-credit-quota.md#applicable-scope)                                                                                                    |
| Roles              | Sums all usage during the period for current role members                         | At the time of consumption, counts usage toward each controlled role the member belongs to, starting only after the role quota takes effect (see [Role Quotas](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/member-credit-quota.md#role-quota)) |
| Update timing      | Accumulated in the background; billing categories are periodically pre-aggregated | Accumulated with each deduction                                                                                                                                                                                                                                   |

To verify an individual deduction, go to <mark style="color:blue;">Credits</mark> → <mark style="color:blue;">Consumption Records</mark> (see [Credits Management Panel](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits.md#consumption-tab)).

## Frequently Asked Questions <a href="#faq" id="faq"></a>

#### Q: Why can't I find the <mark style="color:blue;">Billing Categories</mark> tab? <a href="#faq-credit-categories-missing" id="faq-credit-categories-missing"></a>

Switch the metric to <mark style="color:blue;">Credits</mark> to display the tab. While you are on this tab, the metric menu is locked to Credits. If the metric menu has no Credits option, your organization does not use Credits billing.

#### Q: Several roles show exactly the same figures. Is this a calculation error? <a href="#faq-identical-roles" id="faq-identical-roles"></a>

Usually, no. When a member belongs to multiple roles, their full usage counts toward each role. If that member is the only person with usage during the period, those roles show identical figures. See [How the Roles Tab Calculates Usage](#role-tab-aggregation).

#### Q: How do I generate a usage report for each member? <a href="#faq-member-report" id="faq-member-report"></a>

Switch to the <mark style="color:blue;">Members</mark> tab, set the date range, and click <mark style="color:blue;">Export Excel</mark>. To report on Credits, switch the metric to <mark style="color:blue;">Credits</mark> before exporting.

#### Q: Where does usage by external visitors appear? <a href="#faq-visitor-usage" id="faq-visitor-usage"></a>

External visitors are not organization members, so they do not appear in the table on the <mark style="color:blue;">Members</mark> tab. View their usage on the <mark style="color:blue;">Contacts</mark> or <mark style="color:blue;">Chat Platforms</mark> tab. In member rankings by Credits, this usage is included under “Unknown”.

#### Q: How can Agent administrators see usage only for the Agents they manage? <a href="#faq-own-agents-only" id="faq-own-agents-only"></a>

Set <mark style="color:blue;">Usage Statistics Scope</mark> for their role to <mark style="color:blue;">Authorized Assistants Only</mark>, and assign only the Agents they manage under <mark style="color:blue;">Assign AI Assistants</mark>. For setup instructions, see [View Usage for Authorized Agents Only](#scope-setup).

#### Q: A role is set to “Authorized Assistants Only”. Why can the member still see the entire organization? <a href="#faq-scope-still-organization" id="faq-scope-still-organization"></a>

Check the member's other roles, including the default role. If any role has <mark style="color:blue;">Usage Statistics Permission</mark> with its scope set to <mark style="color:blue;">Entire Organization</mark>, the member can see the entire organization. Owners always see the entire organization. See [The Scope Members Actually See](#scope-resolution).


---

# 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/others/usage-statistics.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.
