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

# Strategy and goal

> Set one goal for your brand, star what you focus on, and say how you no longer want to be known.

Open **Strategy** to set your goal, choose your focus and edit how you want your brand to be known.

## The goal

Before you set a goal, **Recommended**, **Mentioned** and **Understood** show your figures for the period chosen at the top of the page, as Visibility and Perception do.

Without a goal, choose **Set up your strategy**. It walks you through your goal, up to three focus topics and how you want to be known, and saves each step as you go. Close it at any point and what you saved stays. Once you have a goal, choose **Edit goal** to change your sentence, its optional **Target: share of answers that recommend you** and **Target date**. The goal is one sentence, such as "Be the platform European founders pick for startup syndicates". Heralded measures it on its questions:

* **Recommended**, the share of answers that recommend you. You can set a target value for it, with an optional date.
* **Mentioned**, the share of answers that name you.
* **Understood**, how closely answers describe you as your brand profile states. See [How AI describes you](https://docs.heralded.ai/methodology/how-ai-describes-you.md).

The goal's questions are the tracked questions of your starred topics in your starred markets. When you star no topic, every tracked question counts. When you star no market, every market counts. A small set of questions can leave a figure [not measured](https://docs.heralded.ai/methodology/empty-figures.md).

### Baseline and progress

Setting the goal fixes its questions and takes the newest [weekly report](https://docs.heralded.ai/concepts/daily-updates-and-weekly-reports.md) as its baseline. If no report exists yet, the first report after you set the goal is the baseline. Each later report compares the newest figures with the baseline over the questions and engines both reports measured, using the same paired test as every other [change](https://docs.heralded.ai/methodology/change.md). A move is called up or down only when that test says it is real.

### Revisions

Changing the goal sentence, your focus, or the four claims Understood judges answers against starts a new revision of the goal. A new revision fixes its own questions and takes a new baseline. Figures never compare across two revisions, so right after a change the goal reads **Not comparable with last week**. Changing only the target keeps the revision and its baseline.

Progress also reads **Not comparable with last week** when a market the goal is measured on changes its setup after the revision started.

## Focus

Star up to three topics, three competitors and three markets. Manage your [markets and audiences](https://docs.heralded.ai/concepts/markets-and-audiences.md) in brand settings. A fourth star of one kind is refused until you remove one.

A star stays when its topic is archived, its competitor stops being tracked or its market is retired. It reads **No longer tracked** until you unstar it.

Each tracked topic keeps its own name and star. Renaming or starring it leaves copies for other markets or audiences unchanged.

### Focus tags on actions

Every [action](https://docs.heralded.ai/concepts/actions.md) carries a focus tag:

* a starred topic, when the work targets that topic or is linked to one of its questions;
* a starred competitor, when the work closes a gap with that competitor;
* outside your focus, otherwise.

A starred topic tags the work before a starred competitor does.

### Focus and the week's suggestions

Work with a focus tag ranks higher when Heralded chooses this week's suggestions, but never above work with a higher [expected gain](https://docs.heralded.ai/concepts/actions.md#expected-gain-and-ranking) that reaches as much demand for the same effort. A site fix that lets AI engines reach and read your site is never pushed out of the week by focus work. Your focus also guides which work Heralded suggests each week.

## Topics

Use **Tracked**, **Suggested** and **Archived** below Focus to manage your topics. Each tracked row shows its market, audience, score, change and questions. A star adds the topic to your focus. Use **Market** and **Audience** in **Filters** to narrow the list.

A topic is one subject in one market for one audience, with up to three questions and its Google searches. Copies for other markets or audiences have their own scores and history. See [Markets and audiences](https://docs.heralded.ai/concepts/markets-and-audiences.md) and your [topic allowance](https://docs.heralded.ai/concepts/usage.md#topics-and-prompts).

## Preview a topic

Choose **Add a topic**, enter its subject and choose a market and audience. The home market and All buyers are prefilled. **Preview questions** shows what Heralded will ask. **Add topic** saves the preview and opens the new topic. Closing the dialog before saving leaves it untracked.

The footer says **Uses 1 topic**, with the workspace allowance and remaining topics when you can see those counts. A refusal preserves the server's limit note. Workspace members who can manage capacity can open Billing to add topics. A member with access to one brand is directed to their workspace owner, and a trial shows its trial note.

## First answers and score

A newly tracked topic or question is new until a weekly report scores it. New topics appear first in the list. Its first-answers time is an estimate until the answers arrive, then it is the answered time. Its first-score date is the next weekly report's date for its market. See [daily updates and weekly reports](https://docs.heralded.ai/concepts/daily-updates-and-weekly-reports.md).

## A topic's score

A topic's Heralded Score uses the AI answers to its questions. All equals AI, and Search keeps Mentioned and Recommended shares without a score or band. The number is the same in the topics list, one topic, the scores read grouped by topic and the topic named on a question. **Mentioned** and **Recommended** come with it, with [change](https://docs.heralded.ai/methodology/change.md) on each share.

Tracked topics remain listed before your first report and when the period holds no content check. Each tracked topic has its own market, audience, questions and score. Copies of a subject in other markets or for other audiences have separate scores. A topic with no question read yet, or too few answers, has no Heralded Score: it reads **Not measured**, with **No question read yet** or **Too few answers** as its reason. The Search side needs at least three keywords with a result page read, as [Search visibility](https://docs.heralded.ai/concepts/prompts.md#google-search) explains, and a side that is not measured has no value. All uses AI even when Search is measured and AI is not. The reads say which sides they cover.

Each topic also names who clearly leads it on AI, you or a competitor. A clear leader has a Heralded Score above the Invisible band, no tied score, and a score interval whose low end is above every other measured brand's score. A tie is not a lead. An unmeasured tracked competitor blocks a lead, but an unmeasured discovered brand does not. A measured topic without a clear leader reads **Too close to call**. A topic where your Heralded Score is not measured reads **Not measured**.

## Your pages for each topic

A topic is served by every page of yours that answers its questions, that AI cites in its answers or that ranks for its keywords. [Topics](https://docs.heralded.ai/concepts/strategy.md#how-heralded-reads-your-pages-for-a-topic) explains how Heralded reads them. A topic can hold several distinct pieces. The pages say what your site has for a topic; the score says how you do on it.

The API also returns the topic's own pages and question coverage. Its page set includes judged pages, own pages cited in the topic's answers and own pages in Google's top 10 for its keywords. Coverage belongs to the selected report. A question is `answered` when a judged page answers it, `unanswered` when at least one page was judged against it and none answers it, or `unknown` when no judgment establishes an answer. An older report without question coverage leaves it unknown.

The topic pane's **Work** list follows the selected period and filters. The [Work page filtered to a topic](https://docs.heralded.ai/concepts/actions.md#one-subject) uses the last four weekly reports.

## How Heralded reads your pages for a topic

Each weekly report reads your pages against the questions you track for each topic and other questions buyers ask about it. A topic's pages are every page of yours that AI cites in its answers, that ranks in Google's top ten for its keywords, or that the content check judged for it, up to ten per tracked topic. Each question ends up answered, unanswered when every page judged against it misses it, or unknown when no page was judged against it. The topic pane shows these pages and, under **Not answered on your site**, the questions none of them answers. They are not a status: how you do on a topic is its score.

The content check also keeps one verdict for each tracked topic, which suggested needs and [actions](https://docs.heralded.ai/concepts/actions.md) read. It is the only judge of whether a page answers a buyer question: Heralded suggests a title and description update for a page only when the page has none. Citation and search counts describe the page separately.

Covered and Weak require answers in the topic's language from a page on your site (in a Europe topic, from any of its countries' versions of your site), in any category group, including **Other**. Templates, template galleries, marketplace listings, campaign landing pages, user content, generated archives and sitemap hosts do not cover the need. Campaign landing pages are never rewrite targets. The category of the address a page lands on in [Website](https://docs.heralded.ai/concepts/website.md) decides whether it is a template listing; a page without a specific category, including one in Other, is also judged by its address. Files such as stylesheets, route patterns and format copies such as markdown mirrors are not pages and are left out. A mirror that names its page as canonical counts as that page. Those pages stay out of the judged candidates and never decide a verdict. A topic is Missing when none of its eligible judged pages answers it. Excluded pages remain in its evidence. The homepage is a target only for your brand's own category. That rule also applies to pages that redirect to it or name it as their canonical page. Outside your primary host, a host whose scope has not been decided stays out until it is included in your site.

Heralded considers titles and addresses across your whole in-scope inventory, including unread pages and large collections. It also considers your sitemaps, cited pages, keyword rankings and Search Console pages. It checks up to three candidates in the Site category group first, including pricing, product, solution and feature pages. If none matches, it checks up to three candidates from the other groups. Among pages with the same verdict, it prefers a Site page. If no inventory candidate matches and language has not already settled the verdict, it searches your site for up to five needs per report and judges up to three search results. Each need allows at most nine page reads, split equally between Site candidates, other inventory candidates and search results. A matching unread page that can cover the need is **Weak**, never **Missing**. Without judged evidence, a search with no hits, a failed search or an unfinished check leaves the topic **Unchecked**.

Locale copies use one candidate slot, ranked using the copy for your topic's language and market. Canonical addresses and confirmed aliases share that slot. Tracking parameters are removed; parameters that identify a distinct page are kept. Heralded assigns rewrite targets across the report, starting with the needs of greatest value. Each need gets its best available Weak page. A page is reused only when no unassigned Weak page remains for the need. The need then gets its best Weak page and can still offer a rewrite. Among pages judged to answer nearly equally well, the title and address's match to the need come first, then how closely the page matches the topic. A rewrite uses your topic's copy. Adding a need to a report preserves the candidate pools already chosen for its other needs.

An idea must fit your brand and answer a buyer's question. A topic can hold several distinct pieces, each with its own title and scope. Each suggested piece targets problems in one language: your topic's language or a language your site publishes in. A Europe topic on a site that publishes only in English gets English pieces, while its keywords are still measured in each country's language. Its title, scope and explanation are English; the piece is written in its target language. Where older problem evidence has no language, the piece uses its other references' language or its topic's language. For a Weak topic, Heralded prefers updating the page when an update is available and its problems concern what that page should answer in its own language. Problems in another language need a new piece in that language. When an update is unavailable, Heralded can suggest a new piece. When one is available, a suggested new piece explains why the page cannot serve those problems. Page coverage and the [topic results](https://docs.heralded.ai/concepts/strategy.md#a-topics-score) are separate: a Covered topic can still have questions where engines do not recommend you or keywords where your pages rank poorly. When per-engine question rates are not measured yet, Heralded can show one rate across engines; per-engine problems replace it once they are measured. Content is one possible solution alongside page updates, outreach and listings.

Up to three of the strongest negative opinions specific to the topic become angles on a piece or page update. An opinion that matches more than half the report's offered ideas is dropped as generic before any angles are selected. Each remaining opinion attaches to at most three ideas, selected by match strength, with a direct match to the idea's topic breaking ties. Generic concerns that apply equally to most topics stay out. Attached opinions create no separate opinion piece.

**Write this** checks for similar open ideas and written pieces in the same brand, market and audience. **You already have work on this:** links to each similar action. **Order anyway** places another order; **Cancel** leaves your work unchanged. The warning spends no content credit. Similarity never prevents you from ordering another piece.

## Suggested topics

Heralded finds buyer needs you do not track and lists them as suggested topics, under **Strategy**, in the **Suggested** topic view. Each says why it is suggested and whether a page of yours answers it. The evidence behind it is in its pane, under **Why this topic**. A preview can reuse its ready draft. Tracking a suggestion without a preview drafts its questions and starts keyword research in the background.

Suggested topic names and needs are in English. Their evidence keeps the original phrasing. For one market and audience, names with the same significant words appear once, including plural and word-order variants. A matching tracked topic hides the suggestion.

When your workspace is at its topic limit, a suggested topic offers **Swap in** when it clearly beats your weakest topic, or **Write this** when no page of yours answers it.

On a suggested topic's row, **Not now** offers two choices. **Later** hides the suggestion until the day you pick: next week, in a month or a date within a year. It comes back unchanged. **Not relevant** hides it for good. Both offer **Undo**.

When your workspace has room for more topics, for example after your trial's first charge, an upgrade or extra topics, Home shows **Topics to track**: the best suggestion for each free place, in Heralded's order. **Track all** tracks them for their suggested markets and audiences, and **All suggestions** opens the **Suggested** view to choose others. Nothing is tracked until you press it. Members who cannot start work don't see it.

Drafting gathers People Also Ask, Reddit and Stack Exchange questions in your topic's market alongside your stored questions and searches. Public research uses public search phrases or your site's category. Questions you enter guide your draft privately. A retry reuses that research. If a public source cannot be read, drafting continues with the evidence available. Your Search Console queries and questions you enter stay private to your brand.

Drafting uses your confirmed brand profile over the latest report's inferred profile. Questions ask for brands of your category's kind, speak for whoever your brand sells to or for the topic's audience, and keep your service area where a local person would name it. [How Heralded chooses questions](https://docs.heralded.ai/concepts/prompts.md#how-heralded-chooses-questions) covers how they are written and checked.

## The topic pane

Open a topic under **Strategy** or in AI visibility, or from a question or keyword, to see it in the side panel. Opened from a question or keyword, it takes that panel's place, with Back to return. Its previous and next buttons, or J and K, step through the full topic list, continuing onto the next page. The position shows the total, such as **1 of 16**. Browser Back returns through the panels you opened. Escape closes the top panel. The header shows the topic's name, one sentence on where you stand, and every filter it is read under. The info button beside the name holds the buyer need. A suggested, stopped or new topic is marked **Suggested**, **Archived** or **New**.

If a tracked topic has a name in another language, members who can start work see its English name with **Use English name** in a notice. Choose it to rename the topic. Its local search term and tracked keywords stay the same.

### A tracked topic

**AI answers** and **Google search** switch the figures and questions shown. AI answers shows Heralded Score, Mentioned and Recommended; Google search shows Mentioned in search and Recommended in search. Each figure has its own small trend and change. The header holds the focus star, market and audience, and Google search adds the number of searches where you rank in the top ten.

**Questions** lists the five weakest questions on AI answers. Google search lists the five most searched keywords, with their monthly searches, English meaning and your rank. Open a row for its panel. **Not answered on your site**, **Who leads**, **Work on this** and **Your pages** follow. The next step opens its work item.

**See all** opens the topic’s full page at that section, where lists page through every row. The page also holds the full trend chart, engines, the other side’s questions or searches, pages AI cites and the answers behind the figures. Properties and figures sit in the right column, or after the title on a phone.

The keyword list says **Low search demand** when research found no searches, and **Search demand unavailable** when it could not measure demand.

### A new topic

A topic remains **New** and **Not measured yet** until a weekly report scores it. Its questions stay visible as **Asking now** or **Answered**, with the date of their first score.

### Adding questions and searches

Members who can start work add to a tracked topic in place:

* **+ Add a question** opens a field under **Questions**. As you type, Heralded checks whether another topic you track fits the question better. If one does, it says "This fits {topic} better. Add it there or keep it here." Choose the topic's name to open it. When the topic has 3 questions, choose **Replace a question** and select the question the new one replaces. A new question is asked within minutes and reads **Asking now**.
* **+ Add a search** under Google searches adds a keyword to the topic. For a Europe topic, it asks for the country. When that country's keyword places are full, it replaces the lowest-volume researched keyword, as [Add a keyword](https://docs.heralded.ai/concepts/prompts.md#add-a-keyword) says. Heralded reads its top 10 on the next daily update.

### The topic's menu

Members who can start work find **Copy to another market or audience**, **Rename** and **Stop tracking** in the topic's menu. Renaming changes only this tracked topic. Stopping tracking keeps its history and offers **Undo**. **Track again** restores it with its original market and audience, subject to your workspace's available topics.

To copy, choose a market and audience, select **Preview questions**, then **Copy topic**. A failed rewrite says "Couldn't write the questions for this audience. Try again." and tracks nothing.

### A suggested topic

A suggested topic's sentence says why it is suggested. **Searches a month** and **Who leads** follow. **Why this topic** stays closed until you open it. It lists the evidence Heralded stored for the need: each phrasing as found and where it came from, with Search Console impressions or monthly Google searches where Heralded already holds the number. For its ten best suggestions, Heralded also reads the questions buyers ask in public (Google's People also ask, Reddit, and Stack Exchange where the market's language is English) when it finds them, so a new brand sees them before its first report. Tracking the topic drafts its questions from the same questions. What AI engines searched while answering your questions sits apart under **AI searched**, because those searches follow questions Heralded chose. Opening it reads stored evidence and never buys research. **Your page** says whether a page of yours answers the need.

**Track topic** tracks it for the suggested market and audience. The panel waits while Heralded drafts its questions. Keyword research follows in the background. If drafting fails, **Try again** sends it again. Past the workspace's topic limit, the limit note shows. When the suggestion clearly beats your weakest topic, **Swap in for** that topic, beside Track topic, stops tracking it for that market and audience and tracks the suggestion in its place. When no page of yours answers the need, **Work on this** offers **Write a page**, which files the piece without tracking the topic; the content credit is spent when the piece starts. **Not relevant** in the **⋯** menu hides the suggestion for good, after you confirm.

## Your buyers' questions

Members who can start work add the questions their buyers ask, from a sales call or a support ticket, in their words. Use **Add a question your buyers ask you** under **Why this topic** on a suggested topic. A question belongs to the topic, for that market and audience, and shows as **Added by your team**. Its **⋯** menu edits or deletes it, and deleting asks you to confirm first.

Only people with access to the brand see your questions. Heralded stores them as evidence for that topic. They never feed a Snapshot, a leaderboard or anything another workspace reads, and adding one changes no question you already track.

## Read topics through the API

A tracked topic's monthly Google demand adds its keywords in every country: the demand of the searches it tracks, not of its whole category. The read exposes a country split and marks the total partial when a volume is unknown. See [topic figures](https://docs.heralded.ai/figures.md#pages-topics-and-audit) for the fields.

`GET /v1/brands/{brand_id}/topics` and MCP `get_topics` list one item per tracked topic, with its `market`, `audience` name and `audience_id`. All buyers has a null audience ID. `view` picks `tracked`, the default, `suggested` or `archived`. The list takes `period`, the figure filters and `sort`, `direction` and `q`. `market` selects topics in a country, Europe or Global; it excludes another market's answers from that country. `audience` selects an audience UUID or `all_buyers`. Omit either filter for every value.

On tracked topics, `band` selects `Invisible`, `Under-visible`, `Emerging`, `Strong`, `Leader` or `Not measured`, using the Heralded Score. `sort` accepts `topic`, `rank`, `ai_score`, `search_score` and `cited_pct` as well as `demand`, the default. Unknown figures sort last in both directions. Filtering and sorting happen before paging. Topics remain listed when the report has no content check.

A tracked or archived topic's `id` identifies that subject in one market for one audience. `tracked_topic_id` repeats it, and `topic_id` links copies of the same subject. A suggested topic's `id` is `s:` and its suggestion id, and it has no score. Each topic carries:

* `state`, `need`, `market`, `audience` and `audience_id`.
* `measurement_status`, `first_answers_at` and `first_score_on`, as [first answers and score](#first-answers-and-score) defines them. The same fields appear on a topic's question rows.
* `scores.all`, `scores.ai` and `scores.search`, each with `value`, `band`, `change`, `mentioned`, `recommended` and `state`. An AI side with no value has `state` `not_measured` or `too_few_answers`, and so does All, which uses AI. Search is `not_scored`. `leader_state` is `measured` when one brand clearly leads and `leader` names it, `no_clear_leader` when your Heralded Score is measured but no brand clearly leads, or `not_measured` when your Heralded Score is not measured. The list and one topic return the same leader and state. `side` orders `winners` and defaults to `all`. `sides_available` names the sides scored.
* `prompts_count`, `prompts_filtered` and `keywords_count`. The filtered count follows market, audience, type, intent and a selected question.
* `band`, `cited_share` and `unanswered_questions`. The [figure definitions](https://docs.heralded.ai/figures.md#pages-topics-and-audit) state their populations and unavailable states.
* On a suggested topic, `demand`, `evidence`, `coverage`, `why_labels`, `best_to_track` and `actions`. Each evidence item has a `kind` and its `text`, an `engines` list, empty except for AI background searches, `impressions` on a Search Console query, and `searches_mo` where Heralded already holds the phrase's monthly Google searches. A question your team added comes last, with `kind` `member_question` and its `id`. `actions` always has `track`. When your workspace has no free topic place, it can add `swap_for` with the topic it replaces, or `write` when no page answers the need. These two choices never appear together. Adding a suggested topic lets you choose its market and audience before saving. An archived topic has its own `archived_at`; it is `null` on tracked and suggested topics.

One topic adds its `pages` (the pages its questions cite most, with how often and whether each is yours), its `keywords` with their countries and languages, `keyword_research` (whether research found none or was unavailable for the topic), its `winners` (the brand and its competitors, best score first, at most five), its scores `by_segment`, its questions and the cited pages [Pages, topics and Audit](https://docs.heralded.ai/figures.md#pages-topics-and-audit) lists. Filter `GET /v1/brands/{brand_id}/scores` by a tracked topic's `id` for its scores. A question's `topic_detail` carries its topic's market, audience and scores.

The list's `leading` and `cards.leading` count topics you clearly lead. `competing` and `cards.competing` count topics in view where your Heralded Score is measured, including those without a clear leader. `lead_sentence` reads `You lead {leading} of {competing} topics.` These counts, `cited_share`, `unanswered_questions` and the Visits from AI card follow the selected topics before search and paging. Visits count each document once even when it serves several topics. `bands` gives the available band choices and their counts before the band filter.

One topic also adds `coverage_questions`, `own_pages`, `ai_score_series` and `live_actions`. Each own page carries its answered-question count, topic citation count, best Google rank, Search clicks and Visits from AI when measured. Each question adds `engines` with Mentioned and Recommended. Keywords add `searches_mo` and `best_rank`. Competitors include their `domain`, `mentioned_change` and `recommended_change` on the selected side. Live actions target the topic, its selected questions or its pages, including content pieces and page rewrites.

Add `with_pane=true` to one topic, on `GET /v1/brands/{brand_id}/topics/{topic_id}` or MCP `get_topics` with a `topic_id`, for the figures a topic page draws. Without it the read is unchanged. With it the topic adds:

* `by_engine`: its figures on each AI engine that answered in the period, in the engines' order. Each row is the one `GET /v1/brands/{brand_id}/scores` serves with `group_by=engine` and `topic`: `prompt_count` and the Heralded Score, Mentioned, Recommended, Understood and Praised, each with its `change`. The period and filters apply, but `engine` does not. An engine with no answers in the period has no row.
* `ai_counts`: how many AI answers mention you and how many recommend you, as `mentioned` and `recommended`. Each has a `numerator`, the `denominator` it is counted over and `answers`, the same three fields as `figures.mentioned` and `figures.recommended` in `GET /v1/brands/{brand_id}/scores` for the same period and filters. A topic without answers has a null `numerator` and `denominator`.
* `search_trend`: Mentioned on the Search side for each weekly report, the points `scores` draws with `side=search`. It is empty when no report checked the topic's keywords.
* `keywords_top10`: how many of its active and paused keywords have one of your pages in the ten results of their latest check. The `segment` filter applies. `keywords_count` is the total.
* `brands` and `brands_total`: the first five of the brand and its competitors, best on `side` first, each with its `rank` and the fields of a `winners` entry. Search has no score, so on `search` they are placed by Mentioned. When you rank lower than fifth, you take the fifth place and keep your rank. `brands_total` counts every brand ranked on the topic, you included.
* `pages_total`: every page its questions cite. `pages` lists the five cited most.

Detail sections follow each applicable figure filter. Keywords, keyword research and frozen coverage follow the selected tracked topic and its questions. Analytics and Search Console figures keep their own measurement windows.

AI engine searches and their Google rank states appear on the triggering [question](https://docs.heralded.ai/concepts/prompts.md#ai-searches-in-the-api).

One tracked or archived topic also carries `search_term` and a cached `english_name_suggestion`, either `null` or `{source_name, name}`. A member who can start work can request the suggestion with `POST /api/domains/{brand_id}/topics/{topic_id}/english-name/preview`, then accept that exact object with `POST /api/domains/{brand_id}/topics/{topic_id}/english-name`. Previewing keeps the current name. Acceptance renames that tracked topic and preserves its subject's search term and tracked keywords. A changed or unoffered suggestion is refused. Suggested topics have no name suggestion.

### Add or copy a tracked topic through the API

`POST /api/domains/{brand_id}/tracked-topics/draft` accepts `text`, an optional subject `topic_id`, `market` and `audience_id`. Omit the market to prefill the brand's home market. Omit the audience for All buyers. Use a market and audience from the brand's lists. The response previews the questions and returns a `suggestion_id`.

`POST /api/domains/{brand_id}/tracked-topics/{id}/copy` previews a copy for another market or audience. Each question is prepared for the destination. Copies to or from a custom audience require every question to be rewritten. An incomplete rewrite returns "Couldn't write the questions for this audience. Try again." and tracks nothing.

Confirm either preview with `POST /api/domains/{brand_id}/tracked-topics/confirm` and its `suggestion_id`. Capacity and the selected market and audience are checked again when saving. The result's `id` identifies the tracked topic; `topic_id` identifies the shared subject. Use the tracked topic's `id` when renaming or changing its tracking status through `PATCH /api/domains/{brand_id}/tracked-topics/{id}`, or starring it through the strategy focus routes. Restoring a topic keeps its market and audience even if either was removed from the lists.

`GET /api/domains/{brand_id}/markets` returns the brand's market list and `home_market`. Replace the list with `PUT` to the same route. Changing the home market leaves existing topics where they are. `GET /api/domains/{brand_id}/audiences` lists custom audiences; `POST`, `PATCH /{id}` and `DELETE /{id}` add, edit and remove them. Editing either list needs settings access; drafting, copying and confirming topics needs permission to start work.

## Periods and connections

**Latest**, **Last 4 weeks**, **Last 12 weeks** and **All time** select report populations, not calendar spans. Strategy opens on Latest, or on the period you last chose on a measurement page. A failed week can fold into the next report. Citations, questions and sources follow the period, engine, type, intent, market and audience filters. **Market** and **Audience** each appear when there is more than one choice. Counts include the daily updates each weekly report pooled. Reports across a change of engines, market or scoring are not pooled.

Each weekly report keeps the citations it counted, so a past period's count stays the same after its answers age out.

**Search clicks** appears with [Search Console](https://docs.heralded.ai/concepts/connections.md#google-search-console). **Visits from AI** appears with [Google Analytics](https://docs.heralded.ai/concepts/connections.md#google-analytics). Both describe the last 28 days, regardless of the citation period, and come from the newest weekly report in the period that read the property connected now. After you connect a different property, they stay empty until a report reads it. The pane shows clicks and the top query with Search Console, and visits from AI with Analytics.

Google Analytics counts sessions AI assistants send to a page over 28 days ending two days before that weekly report started. It includes Google Analytics' AI Assistant channel and known AI assistant sources. Landing pages omit query strings, so a page selected by a query such as `?p=123` stays unmeasured unless it has a measured path-only alias. A visit without a referrer counts as direct, and many visits from AI apps arrive that way. Treat **Visits from AI** as a floor. Figures appear after the first report that reads the connection.

The shared page pane also shows the [page's stats](https://docs.heralded.ai/concepts/website.md#page-stats). Their crawler, live-fetch, search and visit figures use the newest pinned weekly report's window, independently of the citation period and filters. The report keeps crawler counts, so opening a past report shows its recorded values. Known aliases and campaign parameters resolve to the same page when the report records visits and crawls.

The page pane shows each tracked topic that includes the page as a label under its title. Its citation trend, engines and page findings follow its figures. [Website](https://docs.heralded.ai/concepts/website.md#pages) covers the shared pane and its **Details** menu.

## How you want to be known

Edit **Category**, **Audience**, **Offer**, **Difference** and your optional buyer profile, then choose **Save**. **Voice** saves each choice at once. These are the same fields as **Settings** › **Brand**. **Brand look** stays in Settings.

**Facts** lists the statements AI should get right. Choose **Add a fact**, enter your text and select **Check**, or pause typing. Review the separate facts, their questions and what counts as agreement. Untick any you do not want to add. You can edit a statement and check it again before saving. Opinions stay unticked with a suggestion of what to track instead. The dialog shows how many places remain out of 20 facts.

Save your selection. A matching fact is already in your list and is not added twice. For a contradiction, choose **Keep both**, **Replace** or **Keep the existing one**, then **Save choices**. Replace keeps the fact's history and starts a new measurement definition. If interpretation is unavailable, nothing is saved.

Each measured fact shows how many answers agree with it out of all checked answers. Before readings arrive, an interpreted fact shows **Checking from** with the next report date when available. **Interpreting**, **Not measurable** and **Brand paused** identify facts awaiting interpretation, opinions and a paused brand. Open a fact for its question, check and author. **Edit wording** changes it and **Remove fact** stops checking it.

## Labels you want to leave behind

Enter one label per line under **Labels you want to leave behind**, then choose **Save**. You can list up to five labels you no longer want AI to describe you with, such as "crowdfunding platform". The list is part of your brand profile. Heralded's weekly suggestions avoid describing you with them.

Each weekly report measures every label: the share of answers naming you that still describe you with it, and the cited pages that repeat it. The change in that share is named only where the [paired test](https://docs.heralded.ai/methodology/change.md) calls it real. A new label is measured from the next report. [Perception](https://docs.heralded.ai/methodology/how-ai-describes-you.md#labels-you-are-moving-away-from) explains the reading.

## Read your strategy through the API

`GET /v1/brands/{brand_id}/strategy` and MCP `get_strategy` return the goal, every revision, your focus and the labels you are moving away from. [Strategy](https://docs.heralded.ai/figures.md#strategy) maps the fields. `GET /v1/brands/{brand_id}/moving-away-from` and MCP `get_perception` with `moving_away_from` return each label's measure, as [Labels you want to leave behind](https://docs.heralded.ai/figures.md#moving-away-from) describes. The API reads your strategy and does not change it.

## Permissions

Members who can start work can edit the goal, star focus items and manage topics. Brand settings permission is needed to edit the brand profile, voice, facts and labels, or add a market. Viewers can read Strategy without write controls.


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