---
title: Monitor search consumption
slug: '1855'
canonical_url: https://docs.coveo.com/en/1855/
collection: manage-an-organization
source_format: adoc
---
# Monitor search consumption
Each Coveo customer [license](https://docs.coveo.com/en/2864/) agreement defines a set of usage [limits](https://docs.coveo.com/en/262/) and quotas.
Administrators and other [members](https://docs.coveo.com/en/2869/) with the [required privileges](#required-privileges) can review these limits and their current statuses from the [**Settings**](https://platform.cloud.coveo.com/admin/#/orgid/settings/license) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/license) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/license) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/license)) page in the [Coveo Administration Console](https://docs.coveo.com/en/183/) (see [Review organization settings and limits](https://docs.coveo.com/en/1562/)).

Search entitlement metrics measure actual search resources consumed by the end users of a solution.
As such, those metrics deserve particular attention and can be visualized in their own dedicated consumption dashboard.

This article provides information to help administrators use the consumption dashboard to accurately monitor search entitlement metrics for their [Coveo organization](https://docs.coveo.com/en/185/).

## Introduction to license entitlements

Usage of the [Coveo Platform](https://docs.coveo.com/en/186/) by end users is licensed in two different ways, depending on the type of deployment:

* Public facing or anonymous search interfaces use an entitlement based on query quotas that are reset on the first day of each month.

* Authenticated search interfaces (private and public facing) can use one of several kinds of per-user entitlements, with no limit on the actual number of queries performed.

Refer to your customer agreement for more details on the entitlements that apply to your contract.
For a complete list of entitlements and limitations applicable to your subscription, see [Product entitlements](https://docs.coveo.com/en/l2590456/).

## Get started with the consumption dashboard

Access the [**Consumption**](https://platform.cloud.coveo.com/admin/#/orgid/settings/license/consumption) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/license/consumption)) dashboard from the **Settings** page in the Coveo Administration Console, under **License** > **Consumption**.

If your license agreement includes search entitlements based on metrics other than queries, select the most appropriate entitlement metric for each search hub.
For search hubs that shouldn't use a [per-user entitlement metric](#user-entitlement), leave the default value [**Queries**](#queries).

Once you're done, the Consumption dashboard header should display accurate totals.

## Consumption dashboard particularities

* The **AdminConsole** search hub represents the search interfaces in the Coveo Administration Console.
Queries originating from this search hub therefore come from the [**Content Browser**](https://platform.cloud.coveo.com/admin/#/orgid/content/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/browser/)) page, for example.

* Queries with _Unassigned_ in the **Search Hub** column didn't originate from a specific [search hub](https://docs.coveo.com/en/1342/).
These queries were however valid, yielded valid results, and counted against your entitlements.
These queries are typically made by developers testing Coveo's search API without specifying the [`searchHub`](https://docs.coveo.com/en/13#operation/searchUsingPost-searchHub) parameter.
A couple of them are acceptable.
However, if you have a large number of unassigned queries, use your usage analytics reports to understand where they come from.
Fix the issue as soon as possible to avoid further impact on machine learning and reporting.

## Query types

There are other types of queries in addition to normal ones, including [_recommendation_](#recommendation-queries) and [_persistent_](#persistent-queries) queries.
Every type consumes quotas uniquely.
For search interfaces where end users aren't individually identifiable, search entitlements are usually based on query quotas that are reset on the first day of each month.

### Queries

Queries refer to the number of times the Coveo Search API was used to retrieve results in search hubs.

Technically speaking, a [query](https://docs.coveo.com/en/231/) is a Coveo Search API request that retrieves query results.
Other uses of the Search API such as requesting field-based or [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [query suggestions](https://docs.coveo.com/en/1015/), generating [search tokens](https://docs.coveo.com/en/1346/), retrieving Quick view data, etc.
aren't counted as queries.

As a rule of thumb, most actions impacting the results or [facets](https://docs.coveo.com/en/198/) being displayed in a search interface count as queries.

**Examples**

Each of the following actions corresponds to a search event with a specific `eventCause` value (for example, `interfaceLoad` or `searchboxSubmit`), and counts as a query:

* Loading a search interface.

* Switching to a different [tab](https://docs.coveo.com/en/1406/).

* Submitting a search request from a search box or IPX interface.

* Selecting a displayed query suggestion.

* Changing the sort criterion or sort direction of search results.

* Switching to a different page of search results.

* Changing the number of results per page.

* Selecting, deselecting, or excluding a facet value.

* Changing the sort order or matching mode of a facet.

* Navigating through search page states using browser history.

* Expanding the result of a threaded conversation (for example, Chatter).

* Any custom code that triggers a search request.

**The following actions aren't counted as queries:**

* Receiving query suggestions while typing keywords in a search page or facet search box.

* Opening a Quick view for a search result.

* Searching in a facet search box without toggling a facet value.

> **Note**
>
> Customer Queries allocation is based on the information shared by customers, depending on the use case and the customer's search page's current traffic.

### Recommendation queries

Recommendation queries originate from [search interfaces](https://docs.coveo.com/en/2741/) that leverage Coveo ML [Content Recommendations (CR)](https://docs.coveo.com/en/1016/), [Product Recommendations (PR)](https://docs.coveo.com/en/3132/), or [IPX Recommendations (IPXRECS)](https://docs.coveo.com/en/p6hh0418/).

What counts as a recommendation query, however, depends on the ML feature:

* **[CR](https://docs.coveo.com/en/1016/)** and **[PR](https://docs.coveo.com/en/3132/)**: Receiving recommendations from the [model](https://docs.coveo.com/en/1012/) counts against the [recommendations per month (RPM)](https://docs.coveo.com/en/1392/) quota.

* **[IPX Recommendations (IPXRECS)](https://docs.coveo.com/en/p6hh0418/)**: Like [CR](https://docs.coveo.com/en/1016/) and [PR](https://docs.coveo.com/en/3132/), receiving IPX recommendations counts against the [recommendations per month (RPM)](https://docs.coveo.com/en/1392/) quota.
One RPM is automatically consumed each time a list of IPX recommendations is generated, which occurs whenever the IPX [search interface](https://docs.coveo.com/en/2741/) loads.

However, submitting a search request in an IPX [search interface](https://docs.coveo.com/en/2741/) is considered a query, which counts against the [queries per month (QPM)](https://docs.coveo.com/en/1391/) quota.

The **Recommendation queries** column appears in the table when at least one search hub received such queries.

For more information on the Coveo ML models, see [Content Recommendations (CR)](https://docs.coveo.com/en/1886/), [Product Recommendations (PR)](https://docs.coveo.com/en/n4b80123/), and [IPX Recommendations (IPXRECS)](https://docs.coveo.com/en/p6hb0337/).

### Persistent queries

> **Important**
>
> Persistent queries are no longer part of product entitlements and have been deprecated.

Persistent queries are typically used to render relatively static, search-based content in a web page or application (see [Render static content using persistent queries](https://docs.coveo.com/en/1009/)).

Persistent queries count against the persistent queries per month quota (that is, they don't count against the queries quota).

Coveo tracks the number of unique persistent queries executed each month (see [Determine persistent query uniqueness](https://docs.coveo.com/en/1009#determine-persistent-query-uniqueness)).
In essence, this means that even if a given unique persistent query is executed a thousand times during a month, it still only counts once against the PQPM quota.
The **Recommendation queries** column appears in the table when at least one search hub received such queries.

### Usage analytics search event count discrepancies

Query counts displayed in the Consumption dashboard measure actual search resource usage at the API level.
In contrast, the _search event count_ [Coveo Analytics](https://docs.coveo.com/en/182/) metric measures end user behavior (see [Search Event Count](https://docs.coveo.com/en/2041#search-event-count)).
An action reported as a single search event in a usage analytics [report](https://docs.coveo.com/en/266/) might have required several queries to be performed.
As such, there might be discrepancies between the counts you see in usage analytics reports and those you see in the Consumption dashboard.

> **Notes**
>
> * Coveo logs duplicate query events, but might not log duplicate search events depending on your search interface UI implementation.
> For example, if a user clicks the search button multiple times with the same query, a separate query event is logged in the Consumption dashboard for each click.
> However, only one search event is logged for JSUI and Headless implementations, while a separate search event is logged for each click for Atomic implementations.
> 
> * [Pager events](https://docs.coveo.com/en/2948#getmoreresults) such as resize (`pagerResize`) and page next (`pagerNext`) are logged as custom events, not search events, but still count as queries.

**Example**

On a community site, a public form allows end users to submit cases to a customer support team.

As the end user is filling the form, contextually relevant query results are automatically displayed as potential solutions to deflect the case.
Those results are updated while the end user fills the form.
Each update triggers a new query that counts against the query quota, although the entire form-filling user action is pushed as a single search event to Coveo UA.

## User entitlement

For search interfaces used by authenticated users, search entitlement is based on the number of [users](https://docs.coveo.com/en/250/), rather than the number of queries.
In the [**Consumption**](https://platform.cloud.coveo.com/admin/#/orgid/settings/license/consumption) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/license/consumption)) dashboard, if your license agreement includes user-based search entitlements, you should typically select an entitlement metric for each appropriate search hub.

For search interfaces identified as per-user, Coveo tracks the number of distinct users that performed queries in the past months.
The exact number of months depends on the entitlement:


|===
| Entitlement | Period accounted for

| Agent Users
| 3 months

| Intranet Users
| 12 months

| Platform Intranet Users
| 12 months

| Platform Agents
| 3 months

| Platform Portal Users
| 12 months

| Salesforce Service Cloud Agents
| 3 months

| Salesforce Sales Cloud Users
| 12 months

| Salesforce Platform Users
| 12 months

| Salesforce Community Cloud Users
| 12 months

| ServiceNow CSM Agent Users
| 3 months

| ServiceNow Fulfillers
| 3 months

| ServiceNow ITSM Users
| 12 months

| ServiceNow HRSD Users
| 12 months

| Dynamics Customer Engagement Users
| 3 months
|===

> **Notes**
>
> * For someone to count as a user, they need to have performed a query in those time frames, depending on their type.
> The period accounted is related to their login frequency (for example, agents log in more often than intranets and partners).
> 
> * In the Consumption dashboard, the number of users displayed for each hub is the distinct user counts for the selected month only.
> For this reason, this value can be lower than the one displayed in the header.

At any time, if the total number of users for an entitlement exceeds the maximum value allowed by the license, the license should be revised.

In this context, unless otherwise specified by the license, queries made from per-user search interfaces don't count against any of the query quotas.

### What's a user?

A _user_ is an identity passed when a query is made in a Coveo-powered search interface (for example, search page, Insight Panel, etc.).

**Examples**

* On an authenticated Intranet search page, each employee counts as a distinct user.

* In the context of Coveo for Salesforce, each authenticated Salesforce user (for example, support agent) using the search interface counts as a distinct user.

> **Note**
>
> When performing a query using many identities, only the first one counts as a distinct user.
> 
> For example, if a query is run using the following identities:
> 
> * `john@doe.com` (Email Security Provider)
> 
> * some-custom-id (Custom Security Provider)
> 
> In that case, only `john@doe.com` would be counted in the user metrics.

## Access a resource consumption graph

You can access a graph to visualize resource consumption evolution for a given search hub over the selected month or the last 12 months.
The graph, however, currently accounts for queries only.

In the [**Consumption**](https://platform.cloud.coveo.com/admin/#/orgid/settings/license/consumption) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/license/consumption)) dashboard, click a search hub, and then click **View Graph** in the Action bar.

> **Note**
>
> The graph displays the daily record of the total number of queries made in the current month.
> As such, future days reflect the most recent total recorded.
> 
> ![Queries graph | Coveo](:https://docs.coveo.com/en/assets/images/manage-an-organization/queries-graph.png)

## Access query logs

You can access an HTML log file listing the queries made in the selected search hub during the selected month, along with their date and time, [query expression](https://docs.coveo.com/en/2830/), etc.
The information in this file can be useful when troubleshooting query usage.

In the [**Consumption**](https://platform.cloud.coveo.com/admin/#/orgid/settings/license/consumption) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/license/consumption)) dashboard, click a search hub, and then click one of the following in the Action bar:

* **View Query Logs** to open the log in a new browser tab.

* **Download Query Logs** to download the HTML log file.


## Required privileges

The following table indicates the privileges required to view or edit elements of the [**Consumption**](https://platform.cloud.coveo.com/admin/#/orgid/settings/license/consumption) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/license/consumption) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/license/consumption)) dashboard and associated panels (see [Manage privileges](https://docs.coveo.com/en/3151/) and [Privilege reference](https://docs.coveo.com/en/1707/)).

[options="header",cols="3,2,1"]
|===
| Action | Service - Domain | Required access level

.3+|View the Consumption dashboard and related activities
|Organization - Activities
|View

|Organization - Organization
|View

|Search - Search Usage Metrics
|View

.3+| Edit the entitlement metric of a search hub
|Organization - Activities
|View

|Organization - Organization
|View

|Search - Search Usage Metrics
|Edit

.4+|View or download a list of the queries performed in a hub during a certain month
|Organization - Activities
|View

|Organization - Organization
|View

|Search - Query Logs
|View

|Search - Search Usage Metrics
|View
|===