Review Organization Search Consumption

Each Coveo Platform customer license agreement defines a set of usage limits and quotas. Administrators and other organization members with the required privileges can review these limits and their current statuses from the Settings panel in the Coveo Administration Console (see Review Organization Settings and Limits).

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.

Introduction to License Entitlements

Usage of the Coveo Platform by end users is licensed in two different ways, depending on the type of deployment:

  • Public facing or anonymous search interfaces generally 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.

Quick Start

Configure the Consumption Dashboard

If your license agreement includes search entitlements based on metrics other than normal queries, follow the steps below to properly set up your Consumption Dashboard.

In the Consumption Dashboard, for each row in the table:

  • If the Search Hub cell value corresponds to a search interface that should use a per-user entitlement, select the most appropriate Entitlement Metric cell value.

  • Otherwise, select the Normal Queries value in the Entitlement Metric cell (this is the default).

The Consumption Dashboard header should now be displaying accurate totals.

Consumption Dashboard Anatomy

You can access the Consumption Dashboard from the Settings panel in the Coveo Administration Console (see Search Consumption Dashboard).

The following annotated screen capture presents the different components of the Consumption Dashboard:

Consumption Dashboard


Shows the running total for each entitlement metric currently accounted for in the dashboard. Also shows which month is selected (2).


Month selector
Click the back and forward arrows to navigate between recorded months to see how resource consumption is evolving in the solution.

When you access the dashboard, the current month is selected by default.


Filter box
Enter text to hide all rows whose Search Hub (4) value doesn't match the specified filter.

Filtering has no impact on the running totals shown in the header (1).


Search Hub column
Each search hub from which a combined total of more than ten normal and recommendation queries were performed during the selected month appears as a separate row in the table. This allows you to monitor resource consumption for each active search interface in the solution. Search hubs from which fewer queries have originated aren't displayed to avoid polluting the table with superfluous information.

  • When the AdminConsole search hub is displayed in this column, it means that the related queries originate from any of the Coveo Administration Console search interfaces (e.g., search interfaces on the Model Testing and Content Browser pages).
  • The total number of normal queries in the header (1) accounts for queries originating from the search hubs which aren't displayed in the table. This means that there may be a slight discrepancy between this total and the one you can obtain by manually summing up the Normal Queries column in the table. Always consider the total in the header to be the accurate one.

Entitlement Metric column
When you first access the dashboard, the Normal Queries entitlement metric is selected by default for each row. To get accurate readings, select the appropriate entitlement metric for each row (see Normal Queries and User Entitlement).

Entitlement metric selections are automatically saved when you change them.


Users, Recommendation Queries, Persistent Queries, and Normal Queries columns
The User cell is taken into account when computing running totals in the header (1) only if a user value is selected in the Entitlement Metric cell (5). Otherwise, if the Normal Queries value is selected, only the Normal Queries, Recommendation Queries and Persistent Queries cells are taken into account for that row.

The Recommendation Queries and Persistent Queries columns appear in the table only if their value is greater than zero for at least one row in the table.


View Graph, View Query Logs, and Download Query Logs icons
When you first access the dashboard, this Action Bar is hidden and appears only once you click on any of the rows under the Search Hub (4).

For details regarding the Action Bar icons, see Access a Resource Consumption Graph and Access Query Logs Graph.

Query Types

Three distinct types of queries are accounted for: normal queries, recommendation queries, and persistent queries. Each type counts against its monthly quota. 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.

Normal Queries

Normal queries refer to the number of times the Coveo Search API was used to retrieve results in search hubs. In the Consumption Dashboard, the Normal Queries entitlement metric is selected by default for each row. For each search hub that isn’t using a per-user entitlement, you should select the Normal Queries entitlement metric.

Technically speaking, a query 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) Query Suggestions (QS), generating search tokens, retrieving quick view data, etc. don’t count as queries.

As a rule of thumb, most actions impacting the results or facets being displayed in a search interface count as queries.

The following actions count as queries:

  • Loading a search interface.

  • Switching to a different tab.

  • Submitting a search request from a search box.

  • 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.

  • Using the search box at the bottom of a facet.

  • Navigating through search page states using browser history.

  • Expanding the result of a threaded conversation (e.g., Chatter).

  • Any custom code that triggers a search request.

The following actions don’t count as queries:

  • Retrieving query suggestions while typing keywords in a search box.

  • Opening a quick view for a search result.

Recommendation Queries

Recommendation queries originate from search interfaces that leverage the Coveo ML Event Recommendations (ER) and Product Recommendations (PR) features.

Recommendation queries count against the recommendations per month (RPM) quota (i.e., they don’t count against the normal queries quota).

Persistent Queries

Persistent queries are typically used to render relatively static, search-based content in a web page or application (see Rendering Static Content Using Persistent Queries).

Persistent queries count against the persistent queries per month (PQPM) quota (i.e., they don’t count against the normal queries quota).

The Coveo Platform tracks the number of unique persistent queries executed each month (see Determining 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.

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 Usage Analytics (Coveo UA) metric measures end user behavior (see Search Event Count). An action reported as a single search event in a usage analytics report may therefore in fact have required several queries to be performed. As such, there may be discrepancies between the counts you see in usage analytics reports and those you see in the Consumption Dashboard.

  • Coveo doesn’t log duplicate search events but logs duplicate queries. For example, if a user repetitively clicks the search button with the same query, only one search event will be logged on the Coveo UA side, but multiple queries will be logged in the Consumption Dashboard.

  • Pager events such as resize (pagerResize) and page next (pagerNext) are logged as custom events, not search events, but still count as queries.

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 regularly 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, rather than the number of queries. In the 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, the Coveo Platform 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
Partner 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
  • 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 (e.g., 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 (e.g., search page, insight panel, etc.).

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

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

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:

  • (Email Security Provider)

  • some-custom-id (Custom Security Provider)

In that case, only 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 normal queries only.

In the Consumption Dashboard, click a search hub, and then in the Action bar, click View Graph.

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, etc. (see About the Query Expression). The information in this file can be useful when troubleshooting query usage.

In the Consumption Dashboard, click a search hub, and then in the Action bar, click one of the following:

  • 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 Dashboard and associated panels (see Manage Privileges and Privilege Reference).

Action Service - Domain Required access level
View the Consumption Dashboard and related activities

Organization - Activities

Search - Search Usage Metrics

Edit the entitlement metric of a search hub

Organization - Activities


Search - Search Usage Metrics

View or download a list of the queries performed in a hub during a certain month

Organization - Activities

Search - Query Logs

Search - Search Usage Metrics

Recommended Articles