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

# Competitors

> The competitors you track, the brands AI names in your answers, and how you rank.

The **Competitors** page ranks your brand and its tracked competitors by [Heralded Score](/methodology/heralded-score). Its opening sentence says where you stand and how many points the closest competitor is ahead or behind, such as "You lead the rivals you track. HubSpot is closest, 54 points behind." When most brand mentions go to brands you don't track, it adds that, for example "Most brand mentions go to other brands (90%)." The sentence never counts competitors, because the leaderboard shows them.

## Your roster

You track up to 10 competitors per brand. Each is read the same way as you. To swap one, stop tracking it and track another. Heralded measures a newly tracked competitor by matching its name in the latest report's answers.

The leaderboard says how many of your 10 places you use, as in "Tracking 7 of 10 competitors". At capacity, **Track** is disabled with a line explaining that you need to stop tracking one first. Readers without permission to edit competitors cannot track or stop tracking them.

## The leaderboard

The filter bar selects the period, engine, type, intent, topic and segment. The leaderboard has ten rows per page. Your row is tinted and tagged **You**, in its ranked position.

| Column | Shows |
| - | - |
| Brand | Rank, logo and name |
| Score | The Heralded Score and a bar in its score band's colour |
| Trend | The score's rise, fall or state |
| Mentioned | How often the answers name the brand |
| Recommended | How often the answers recommend the brand |

**Score** starts highest first. Select another header to sort by that column, then select it again to reverse the order. **Brand** starts A to Z. A missing score shows “–”. A competitor you started tracking since the last weekly report has no figures yet, so its row says **Measured from the next report** instead of a row of dashes.

[Share of voice](/methodology/share-of-voice) appears once, in its own box above the leaderboard.

## Discovered brands

**Discovered** lists brands AI names in your answers that you don't track. Each cell shows the brand's logo, how often it is mentioned, its answer and prompt counts, its score and **Track**. **New** marks a brand first seen in the period. A score needs at least three answers naming the brand. Otherwise it shows “–” with **Not enough answers for a score**.

Discovery combines a competitor's name and domain aliases into one brand. It includes discoveries from every weekly scan in the selected period. The prompt pane shows only the discovered brands named by that prompt's selected answers, with figures for that prompt.

Search-based competitor research uses each segment's market and language. A market without keyword-research coverage has no measured search-based competitor list. Brands AI names in your answers remain discoverable.

Open a cell to read the brand's pane. **Track** adds it to your tracked competitors. Cells sit two to a row, or one to a row on a phone.

The [customer API](/developers) returns tracked competitors' figures, discovered brands' Heralded Score and a separate list of channels over your selected period. It also lets you read one competitor's score, trend, comparisons, prompts, engines and cited pages. [Figures in the API](/figures#competitors) describes the fields.

## A competitor's pane

Open a competitor's leaderboard row or a discovered cell to compare that brand with yours over the selected period and filters. The pane shows its score, **Mentioned**, **Recommended** and **Praised**, with your values beside them. The comparison sentence says whether you are ahead, behind or level. Engine cards compare both scores and show the signed score gap. Open a card to read that engine's pane for your brand under the same period and filters.

**Score** shows weekly reports. **Lost prompts** lists the gaps where the competitor's score is above yours, widest first. **Won prompts** lists the reverse. Each starts with three prompts; use its pager to read the rest under the same period and filters. Open a row to read the prompt's pane.

**Cited pages** lists the competitor's five most cited pages. Open a page to read its pane. **All cited pages** opens that site's pane on [Sources](/concepts/sources) with the same period and filters. The closing answers link opens the answers naming the competitor under the same period and filters.

A block with nothing measured keeps its place and explains that tracking the brand measures it. A tracked competitor has **Stop tracking** in the **⋯** menu at the bottom-left of its pane, which asks you to confirm first. A discovered brand has **Track** as its primary action at the bottom-right instead, disabled at capacity.

## Channels

Social and content platforms, such as YouTube, LinkedIn, Reddit and Medium, show up in answers too. Heralded treats them as channels. They take their share of the answers but are never ranked as competitors.

## Alerts

The **Competitors** item on the rail counts alerts you haven't seen. It counts a tracked competitor's real share-of-voice move, up or down. It also counts a new competitor when a weekly report first names it in at least 3 answers on at least 2 prompts, or in at least half as many answers as your brand. The count is yours alone and clears when you open the page.


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