> ## 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. # Topics > The buyer needs you track, where you track them and how each one scores. 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](/concepts/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](/concepts/usage#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](/methodology/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](/concepts/content#topics) 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, in the **Suggested** view of [Content](/concepts/content#suggested-topics). Each comes with the searches and questions behind it, including the AI engines that ran background searches, 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](/concepts/content#the-topic-pane) 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](/concepts/content#topics) states. * On a suggested topic, `demand`, `evidence`, `coverage`, `why_labels`, `best_to_track` and `actions`. Each evidence item has an `engines` list, empty except for AI background searches. `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. An archived topic has `archived_at`, the latest archive time across its segments; it is `null` on tracked and suggested topics. 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](/figures#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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.