Search analytics and the read audit trail
See what people search for, what finds nothing and which results get loaded, and who read which release. Learn what is logged, for how long and what stays out of the log.
Two reports answer two different questions. Search analytics asks what your people and agents look for, and whether they find it. The read audit trail asks who read what. Both need the repos:admin scope, and both are limited to your own organization.
What does search analytics show?
Edition and plan: the search_analytics feature. It is in Cloud Team and above, and in the Community edition.
| Report | What it answers |
|---|---|
| Top queries | The queries that are searched most, with how often each found nothing, how often it abstained and when it last ran. |
| Zero-result queries | The queries that found nothing, how many of them abstained and how many were degraded because a channel failed. |
| Daily totals | Searches, zero results, abstentions, degraded searches and failures per channel, for each day. |
| Loads after search | How often a search is followed by a load of a result, and which skills were loaded. This is the signal that a result was useful. |
| One query | A single query over time, with the skills it returned, their best rank and what was loaded afterwards. |
Use it to find the skill that nobody can find, a description that does not say when to use the skill, and a task that no skill covers yet. Pair a zero-result query with a routing test so the gap stays fixed.
What does the search log keep?
Only an organization whose plan has search_analytics has a search log. Such a plan writes one entry for each search that a signed-in person or key makes inside the organization. An anonymous search is logged without an identity, and a search that names no organization, such as a search of the whole public library, is not logged.
By default an entry keeps a hash of the query and its length, and not its words. The hash is of the case-folded query, so two searches that differ only in case count as one. It is a keyed hash: HMAC-SHA-256 under a key that the deployment derives from its authentication secret. A person who can read the log cannot test a guess against a hash without that key, and the same query has a different hash in another deployment. If you rotate the authentication secret, the same query gets a new hash, so the reports count the queries before and after the rotation as different queries. The length counts the characters (Unicode code points) of the cleaned text. For each search it also keeps the mode and scope, the first ten hits with their ranks, whether the search abstained and why, the confidence of the best hit, which channels failed and how long the search took. It names the reader by kind and identifier. It holds no skill content and no token.
The search log has three positions: off, hash and length only, and words too. An administrator of the organization chooses one with the switch "What the search log keeps". The switch is on the Search page of the dashboard and in the settings of the organization, and each position says what it stores. The third position keeps the words too. You can set it through the API as well: send PUT /v1/orgs/{org}/insights/search/settings with search_log_enabled set to true and search_log_query_text set to true. From then on, a new entry also carries the query text: trimmed, with white space folded to single spaces, cleaned of control characters and cut at 300 UTF-16 code units, which is 300 characters for ordinary text. This is the only way that the words of a query reach the log. An entry that was written while the text was off has none, and switching the text on later does not recover it. Without text, the reports still count how often a query ran, how often it found nothing and which results were loaded. They name a query by its length and the first 12 characters of its hash, such as "A query of 24 characters (words not kept), hash 3fa91c07d2be", and they cannot show what it said. The filter that looks for words inside a query finds nothing in entries that have no text. Switch the words on when you want to read the queries, and tell your team before you do, because a query can hold anything a person typed. Each change of this setting is recorded in the activity log as a settings.changed event that names the setting and its new value.
The log can be switched off too, in the first position of the same switch or with the same request and search_log_enabled set to false. The server then writes no new entry for the organization, and the entries already written stay until they expire. The settings can be read and changed even when the plan has no analytics, so an organization can always stop its log. Entries expire after the audit log retention of the plan: 90 days on Cloud Team and 365 on Cloud Business. A deployment on a plan with no limit, such as Community, keeps them for the number of days in SKAAS_EVENT_RETENTION_DAYS, which is 365 unless you change it. The reports need the search_analytics feature, so a plan without it cannot read the log.
Never put a secret in a query, whatever the setting is. The skaas-use skill tells assistants the same.
What is the read audit trail?
A record of each read that succeeded, with who made it, so you can answer who loaded a release before you withdrew it. Each entry holds the time, the action (search, catalog, get or resource), how it arrived (mcp, rest or bridge), the MCP tool, the reader, the repository, the skill, the release hash and the size. It holds no skill content and no query text.
Edition and plan: the read_audit_trail feature, which is in the commercial edition. See Commercial features. The trail is also written, and kept for the audit log retention of the plan, when the plan has search analytics, because the loads-after-search report joins it to each search. Without the audit trail feature you cannot list it.
Filter the trail by skill, reader, repository, action and period. An export in JSON Lines or CSV, with a hash chain that shows whether a record was changed, is described under Commercial features.
What is not logged?
A read by someone who is not signed in, such as a visitor of the public library. A read by a person who is not a member of your organization, such as a reader of your public repository. A read that failed. A read outside an organization. A plan that keeps no audit log logs nothing. The server never logs skill content, prompts, tokens or connection strings.