---
title: "Help Customers Find Answers with External KB Search"
sidebarTitle: "Search & Discovery"
description: "Understand how External KB search works, optimize your articles for discoverability, and use search analytics to close content gaps."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

Search is the primary way customers navigate your External KB. Rather than browsing through a hierarchy of products and categories, most customers type a question or keyword and expect an immediate, relevant answer. The quality of your search results depends directly on how well your articles are written, titled, and tagged — and this page walks you through every lever you can pull to improve the experience.

## How Search Works

The External KB search engine runs full-text search across all published articles that the signed-in customer (or anonymous visitor, for public content) is authorized to see. Results are scoped automatically: a customer who only has access to one product hub will only see results from that product, regardless of how broad their query is.

Search results rank articles based on three signals:

<Columns cols={3}>
  <Card title="Article Title" icon="heading" href="/external/access/search-and-discovery">
    The strongest ranking signal. An exact or close match between the search query and the article title pushes that article to the top of results.
  </Card>
  <Card title="Body Text" icon="align-left" href="/external/access/search-and-discovery">
    Full-text matches within the article body contribute to relevance. Frequency and proximity of the matched terms both influence ranking.
  </Card>
  <Card title="Tags" icon="tag" href="/external/access/search-and-discovery">
    Tags represent the vocabulary your customers use. Matching a query against a tag boosts the article even if the exact phrase doesn't appear in the title or body.
  </Card>
</Columns>

## Improving Search Relevance for Your Articles

Making small, deliberate choices when writing and publishing articles has a measurable impact on how easily customers find them.

**Write titles in customer language.** Use the words your customers would type, not internal product terminology. "How to connect Salesforce" ranks better for typical customer queries than "CRM integration initialization procedure."

**Add tags that reflect how customers ask questions.** A customer might search "sync not working" rather than "data synchronization error." Add tags for common phrasings, synonyms, and error messages that relate to the article's topic.

**Use clear, descriptive headings within articles.** When a search query closely matches a heading inside an article, the KB can surface that specific section as a result snippet. Short, keyword-rich headings (`## Reset your API key` rather than `## Troubleshooting`) improve this section-level surfacing.

**Keep one topic per article.** Narrow articles rank better than broad ones because the content density around a specific topic is higher, which increases relevance scores for queries on that topic.

## Tagging an Article for Better Discoverability

<Steps>
  <Step title="Open the article editor">
    Navigate to External KB, select the product that contains the article, and click the article title to open it in the editor.
  </Step>
  <Step title="Scroll to the Metadata panel">
    In the right-hand sidebar, scroll down to the **Metadata** section. If you do not see it, click the **Metadata** tab icon or expand the sidebar panel. The Metadata section contains fields for tags, category, and SEO description.
  </Step>
  <Step title="Add 3–5 tags that reflect common customer questions">
    Type each tag and press **Enter** or **comma** to add it. Aim for tags that represent the vocabulary your customers use when they experience the problem or task this article addresses. For example, for an article about resetting an API key, good tags include: `api key`, `reset credentials`, `authentication error`, `regenerate token`, `access denied`.
  </Step>
  <Step title="Save and republish the article">
    Click **Save** to store your changes, then click **Publish** (or **Republish** if the article was already live). The updated tags are indexed within a few minutes and begin influencing search rankings on the next query.
  </Step>
</Steps>

## Search Analytics

Your External KB records every search query your customers run. You can access this data in External KB → Analytics → Search to understand what your customers are looking for and where your content falls short.

The Search Analytics dashboard surfaces three key views:

<Tabs>
  <Tab title="Top Queries">
    A ranked list of the most frequently searched terms over a selected time window (last 7, 30, or 90 days). Use this view to confirm that your highest-traffic articles are well-optimized and easy to find. If a common query is leading to an unexpected article — or a low-quality one — improve that article's title and tags.
  </Tab>
  <Tab title="Zero-Result Searches">
    Queries that returned no articles at all. This is the most actionable view in search analytics. Each entry here represents a customer who came to your KB with a real question and left without an answer. Sort this list by frequency to identify the highest-priority content gaps to address.
  </Tab>
  <Tab title="Low-Click Results">
    Queries that returned results, but where the customer did not click any of them. This indicates a relevance problem: your KB has content on the topic, but the titles or snippets shown in search results are not matching what the customer expected to find. Review the top results for these queries and improve their titles, tags, or metadata descriptions.
  </Tab>
</Tabs>

<Tip>
  Review your zero-result search queries at least once a week. Any query that appears three or more times with no results represents a real content gap that multiple customers have hit. Create a new article to address it, add relevant tags, and the gap closes automatically — no changes to the search configuration needed.
</Tip>

## Filtering Search Results

Customers can narrow their search results directly within the KB search experience using two filters:

- **Product filter** — restricts results to a single product hub. Customers can select one or more products from a dropdown that appears above the results list. Only products they have access to appear in the filter.
- **Topic category filter** — restricts results to a specific category within a product (e.g., "Getting Started," "Billing," "API Reference"). Categories are defined when you organize articles in the product hub structure.

Filters are applied interactively — the results list updates immediately as a customer adds or removes filter selections, with no page reload required.

<Note>
  **Search improvements benefit your AI agent too.** Your AI agent uses the same search index as the in-product KB search experience. When you improve an article's title, body, or tags to rank better in customer-facing search, those same improvements also make it more likely that the AI agent surfaces that article when answering related questions. Better KB discoverability and better AI agent answer quality are the same investment.
</Note>

## Frequently Asked Questions

<Accordion title="How long after publishing does an article appear in search?">
  Newly published articles are indexed within **2–5 minutes** of publication. During that window, the article is accessible via its direct URL but will not appear in search results. If an article is not appearing after 10 minutes, check that its visibility is set to a state accessible to the searching user, and that it has not been saved as a draft rather than published.
</Accordion>

<Accordion title="Can I pin certain articles to the top of search results?">
  Yes. You can promote up to five articles per product hub to **Featured** status. Featured articles appear in a highlighted row above organic search results whenever a query is relevant to their tags. To feature an article, open it in the editor, go to the Metadata panel, and toggle **Feature this article**. Featuring works best for your most important onboarding guides, FAQs, and high-traffic troubleshooting articles.
</Accordion>

<Accordion title="What characters are supported in tags?">
  Tags support letters, numbers, spaces, hyphens (`-`), underscores (`_`), and forward slashes (`/`) — useful for versioned tags like `v2/api` or `v3/webhooks`. Commas, quotes, angle brackets, and other special characters are stripped automatically when you save. Tags are case-insensitive: `API Key` and `api key` are treated as the same tag. Each tag can be up to 64 characters long, and each article supports a maximum of 20 tags.
</Accordion>