> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search visibility

> What buyers find when they search Google for your topics, and how Heralded scores your keywords.

**Search visibility** is the Search side of the [Heralded Score](/methodology/heralded-score#the-search-side). It measures whether the pages buyers click on Google show you, and whether a third party on them recommends you. The AI side measures the same for AI answers, and All weighs the two.

## Keywords

A **keyword** is how a buyer searches Google for a topic, in one segment. A topic holds up to ten active keywords in each segment you track it in, beside its prompts. See [Topics](/concepts/topics).

Heralded reads Google's top 10 results for each keyword twice a week, in the market and language of the keyword's segment. A segment with no market reads the United States in English. Each weekly report freezes those checks, so a figure never moves when a page or a search volume changes later.

A keyword that names your brand or a competitor stays out of the score. It is still listed.

## What a keyword shows

| Figure | Means |
| - | - |
| Searches a month | The keyword's monthly Google searches in the segment's market now. Empty when no volume is known. |
| Best rank | Your best position among the ten results of the latest check. Empty when none of your pages is there. |
| Top 10 naming you | How many of the ten results name you. Your own pages count, and so does any other page Heralded read that names you. |
| Clicks showing you | The share of clicks that land on a page showing you. |
| Score | The keyword's Heralded Score, from Mentioned and Recommended as the next section says. |
| AI searches it too | The AI engines whose background searches for the topic's prompts contain the keyword. |

## How a keyword scores

Each result in the top 10 takes a share of the clicks by its position. A result on your own site counts toward **Mentioned**. A result on another site counts toward Mentioned when Heralded's reading of the page says it names you, and toward **Recommended** when the reading says it recommends you. Your own pages never count as a recommendation. The score is the mean of Mentioned and Recommended, placed on the Search side's calibrated scale. [The Search side](/methodology/heralded-score#the-search-side) gives the click shares and the scale.

A page Heralded has not read counts as not naming you, and its share is shown as unread. So an unread page can lower a figure and widen its range, and never raise it. A keyword's range runs from the share Heralded read to that share plus the unread share. A keyword is shown once one check has fetched its results.

## The Search visibility page

**Search visibility** shows the Search side on its own, under the **Segment**, **Period** and **Topic** filters. It opens with your Search score, its change and the share of your Heralded Score the Search side carries. **Mentioned** and **Recommended** follow, read from Google results by share of clicks, then **Understood** and **Praised**, read from the Google results that name you. A page has no segment or topic, so under a **Segment** or **Topic** filter the page leaves Understood and Praised out. **Competitors in search** ranks you and your competitors on the Search side.

The keywords table gives each keyword's Google market, topic, searches a month, best rank, results naming you in the top 10, clicks showing you, score and trend. **Tracked** lists the keywords Heralded reads now. **Archived** lists the keywords you archived and those whose topic is archived in their segment. A paused keyword stays under **Tracked**, marked **Paused**.

Open a keyword to see its pane. The header gives its monthly searches, your best rank and its Google market. **Score**, **Mentioned** and **Recommended** come first. Where Heralded has not read some results yet, each shows a range from what it read to what the unread results could add. Then come the keyword's topic and **The top 10 on Google**, with each result's share of clicks and whether it names or recommends you. Your own pages show **No, not earned**, because they never count as a recommendation. **Prompts that make AI search this** lists the topic's prompts in the segment, those whose background searches contained the keyword first, with the engines that ran them. **Tasks for its pages** lists the open tasks about your pages in the results.

Members who can start work find **Pause keyword** and **Archive keyword** in the pane's ⋯ menu. Archiving asks you to confirm. A paused keyword offers **Resume keyword**, and an archived one **Restore keyword**. Bringing a keyword back counts toward its topic's ten.

## Add a keyword

Select **Add a keyword**, enter what a buyer searches on Google, and choose a topic tracked in the selected segment. Adding a keyword to a tracked topic uses no topic place. A topic holds up to ten active keywords in each segment. If it already has ten, the pane asks you to archive one first. Choose **Create a topic from this keyword** to track a new topic from it instead, which drafts the topic's prompts and keywords. Heralded reads a new keyword's top 10 at the next check.

## Read search visibility through the API

Every figure here is also in the API, and each has the same value wherever you read it.

* `side` on the overview, scores, competitors and topics reads the AI side, the Search side or All. [Sides](/figures#sides) states how.
* A topic's `scores` carry `all`, `ai` and `search`. See [Topics](/concepts/topics#read-topics-through-the-api).
* `GET /v1/brands/{brand_id}/keywords` and MCP `get_keywords` read the keywords. [Keywords](/figures#keywords) lists their fields.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.