Skip to main content
A topic is a buyer need you track, such as “CRM that tracks sales emails”. Each topic holds the prompts buyers ask AI and the keywords they search on Google. You track a topic in one or more segments and read it there, in that segment’s market and language. A topic holds up to three active prompts and ten active keywords in each segment. Your plan sets how many topics a segment holds, and you see that limit only when you add a topic past it. See Topics and prompts.

​
A topic’s score

A topic has its own Heralded Score, built from the AI answers to its prompts. It is the same figure as the score of every prompt of the topic taken together, so the number is the same wherever you meet it: the topics list, one topic, the scores read grouped by topic and the topic named on a prompt. Mentioned and Recommended come with it, with the change and band every score carries. Before your first weekly report, or when the period holds no content check, a tracked topic lists with a null status, page and citations. A topic tracked in several segments pools its answers across them. One topic shows each segment’s score on its own. A topic with no prompt read yet, or too few answers, shows no score. Only AI answers are scored today. The search side joins the score later and the reads say which sides they cover. Each topic also names who leads it. That is the brand with the best score on the topic’s prompts, you or one of the competitors you track.

​
Your page for each topic

Each topic is paired with your page for it, its status and an action. That is the Content page. A topic Heralded has not read yet shows as missing until the next weekly report.

​
Suggested topics

Heralded finds buyer needs you do not track and lists them as suggested topics. Each comes with the searches and questions behind it, why it is suggested and whether a page of yours answers it. Nothing is drafted until you track it. Tracking a suggested topic drafts two to three prompts and up to ten keywords for it. When a segment 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. Dismiss a suggestion to hide it for good.

​
The topic pane

Open a topic on Content to see it in one pane. The header shows the topic’s name, its need, the period, its status and the segments you track it in. A suggested or archived topic is marked Suggested or Archived. A tracked topic starts with its AI score, its band and change, and its Mentioned and Recommended. Your page and its checks follow, then Tasks, the open work about the topic’s prompts. Below the questions, prompts and cited pages, Who wins this topic lists the five best scores among you and your competitors. By segment gives the topic’s score in each segment when you track it in more than one. The pane ends with the segments the topic is tracked in. Members who can start work find Topic options in the pane’s ⋯ menu:
  • Stop tracking in a segment stops reading the topic’s prompts and keywords there. Their history is kept.
  • Rename topic changes its name. Two topics of a brand cannot share a name.
  • Archive topic stops tracking it in every segment.
Stopping and archiving each ask you to confirm first. An archived topic offers Restore topic. When it was archived in more than one segment, tick the segments to restore it in. Restoring takes a place in each segment, so a full segment shows its limit instead. When one segment refuses after others changed, a message names both and the pane shows where the topic stands. A suggested topic says why it is suggested and whether a page of yours answers it. What buyers ask and search lists the Search Console queries, AI background searches and category prompts behind it, each with how often Heralded saw it. Track topic tracks it in the segment the Segment filter selects, or in your Default segment when the filter shows every segment. The pane waits while Heralded drafts its prompts and keywords. If drafting fails, Try again sends it again. Past the segment’s limit, the limit note replaces the suggestion’s note. When the suggestion clearly beats your weakest topic, Swap in for that topic archives it in the segment and tracks the suggestion in its place. Write this appears when no page of yours answers the need. It files the piece’s task without tracking the topic, and the content credit is spent when the task starts.

​
Read topics through the API

GET /v1/brands/{brand_id}/topics and the MCP tool get_topics list topics. view picks tracked, the default, suggested or archived. The list takes period, the figure filters and sort, direction and q. On view=suggested, segment narrows the suggestions to one segment, by its label. A tracked or archived topic’s id is its UUID. A suggested topic’s id is s: and its suggestion id, and it has no score. Each topic carries:
  • state, need and the segments it is tracked, archived or suggested in.
  • scores.ai, with value, band, change, mentioned and recommended, and leader. sides_available names the sides scored.
  • prompts_count and keywords_count.
  • The page, status, citation and action fields Content states.
  • On a suggested topic, demand, evidence, coverage, why_labels, best_to_track and actions. actions always has track, adds swap_for with the topic it replaces, and adds write when no page answers the need. These are for the segment segment names, or your Default segment without one, where tracking from the app puts the topic.
One topic adds its pages (the pages its prompts cite most, with how often and whether each is yours), its keywords, its winners (the brand and its rivals, best score first, at most five), its scores by_segment, the open tasks about its prompts, and the questions, prompts and cited pages Pages, topics and Audit lists. GET /v1/brands/{brand_id}/scores with group_by=topic states the same scores for every tracked topic, and a prompt’s topic_detail carries its topic’s.