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

# Competitor Heatmap

> Show a color-coded matrix of mention/citation percentages by topic (rows) versus brand + competitors (columns), so users can spot visibility gaps and drill into specific competitor/topic combinations.

<Card title="Open in AthenaHQ" icon="arrow-up-right-from-square" href="https://app.athenahq.ai/heatmap" horizontal>
  `app.athenahq.ai/heatmap`
</Card>

## Purpose

The Competitor Heatmap provides a bird's-eye view of your brand's AI search visibility compared directly against your tracked competitors. It displays a color-coded matrix where rows are topics and columns are competitors, allowing you to easily spot visibility gaps or areas of dominance at a glance.

This page is essential for competitive analysis. If you notice a competitor has a highly saturated, dark-colored cell for a specific topic where your brand's cell is light, you can instantly click into it to drill down into the exact prompt responses driving their success.

## What's on the page

* **Page header:** Displays the title "Competitors vs Topics Heatmap".
* **Filter row:** A contextual filter bar allowing you to slice the data. Filters include:
  * **Date range:** Which responses (by date) are aggregated into the heatmap metrics.
  * **Models:** Which AI models' responses are included (e.g., ChatGPT, Claude, Gemini).
  * **Prompt status:** Filters by active, paused, etc.
  * **Locations:** Filters responses to selected geographic locations.
  * **Personas:** Filters responses to selected personas.
  * **Prompt variation:** Filters by prompt variation type.
  * **Prompt tags:** Filters prompts by tag, with options for `is any of`, `is not any of`, or `has all of`.
  * **Prompts:** Restricts the view to specific individual prompts.
  * **Owned domains:** Filters which of your brand's owned domains are considered.
  * **Competitors:** Restricts heatmap columns to selected competitors (your brand's column is always shown).
  * **Mention %:** Filters out columns whose topics don't meet a specific mention percentage threshold or operator (e.g., greater than).
  * **Sentiment %:** Filters out columns whose topics don't meet a specific sentiment percentage threshold.
* **Metric toggle:** A tab selector to switch the heatmap's displayed metric between **Mention %** and **Citation %**.
* **More options menu (⋯):** A kebab dropdown menu in the top right that houses the Export action.
* **Heatmap matrix:** The core visualization chart.
  * **Rows:** Represent the topics tracked by your brand, sorted alphabetically.
  * **Columns:** Represent your brand (highlighted, typically pinned first) and your competitors (sorted alphabetically). Each header includes the company's logo and name.
  * **Cells:** Show the metric value as a percentage. Color intensity scales with the metric value up to the matrix maximum. Cells without data display a dash (`–`).
* **Footer summary bar:** Shows a count of the topics and competitors currently displayed (e.g., "Showing 10 topics across 3 competitors").
* **No competitors blank state:** If you haven't tracked any competitors yet, you will see a blurred out, decorative mock table underneath an overlay titled "No Competitors Yet" with an "Add Competitor" button.

### Drilldowns

* **Click a data cell in the heatmap:** Navigates directly to the Prompts page. This drilldown pre-applies filters for the clicked competitor and the specific prompts associated with that topic row, allowing you to read the exact AI responses driving that percentage.

## What you can do here

* **Switch metrics:** Click the "Mention %" or "Citation %" tabs to change the data the heatmap visualizes. This updates the URL so you can share a link to a specific metric view.
* **Export to CSV:** Click the `⋯` (More options) menu in the top right and select **Export**. On mobile, this is located in the sticky action menu. This downloads a CSV of the currently filtered and ordered heatmap data.
* **Drill down:** Click any cell in the heatmap to navigate to the Prompts page with the relevant competitor and topic filters applied.
* **Reorder columns:** Drag and drop competitor column headers left or right to rearrange them for side-by-side comparison.
* **Pin/unpin columns:** Use the header controls to pin a column so it stays fixed on the left side of the matrix as you scroll horizontally.
* **Sort rows:** Click the sort control on any column header to sort the topics (rows) by that specific column's values in ascending, descending, or unsorted order.
* **Add competitors:** If your heatmap is empty, click the "Add Competitor" button in the blank state overlay to navigate to the Competitors page and set them up.

## Data shown

The heatmap displays aggregate mention, citation, and sentiment percentages for your brand and your tracked competitors, grouped by the topics you have configured in your workspace. The data is pulled directly from the AI responses collected for those topics over your selected date range. Column header logos are pulled automatically based on the competitor's domain.

## Common workflows

**1. Compare brand vs competitors on a metric**

1. Navigate to the Heatmap page.
2. Choose either the "Mention %" or "Citation %" tab depending on your goal.
3. Scan the matrix for weak topics in your brand's column (look for lighter colored cells compared to darker competitor cells in the same row).
4. Optionally, drag column headers to reorder them, or pin specific competitors to keep them side-by-side with your brand.

**2. Drill into a visibility gap**

1. Locate a dark cell for a competitor on a topic where your brand is struggling.
2. Click the cell directly.
3. You are automatically navigated to the Prompts page, which is now pre-filtered to show only that competitor and the prompts tied to that topic.
4. Review the underlying AI responses to understand why the competitor was recommended.

**3. Export filtered heatmap data**

1. Apply any desired filters (e.g., specific date ranges, models, or competitor subsets).
2. Reorder or pin columns to your liking (this visual order is preserved in the export).
3. Open the `⋯` menu next to the metric tabs and click **Export**.
4. If you are on a qualifying paid plan, your CSV will download immediately. If you are on a free plan, you will see an upgrade prompt.

**4. Setting up for the first time**

1. Land on the Heatmap page with zero tracked competitors.
2. See the blurred mock table with the "No Competitors Yet" overlay.
3. Click "Add Competitor" to go to the Competitors page and configure domains to track.

## Empty, loading, and error states

* **Loading:** An animated loader is shown in place of the matrix while competitors or heatmap data are being fetched.
* **Empty:** If you apply filters that yield no results, the matrix area displays "No data available for the selected filters." and the footer says "No topics or competitors to display". If you have no competitors configured at all, you see a full-page blurred mock table with an "Add Competitor" CTA.
* **Error:** If the data fails to load due to a system issue, it fails silently and surfaces the standard "no data" empty state without a distinct error banner.

## Linked from / links to

* **Linked from:** The main app sidebar navigation, under the "Competitors" or analysis section.
* **Links to:**
  * The **Competitors** setup page (via the blank state CTA).
  * The **Prompts** page (via clicking any heatmap data cell).

## Common support questions

**Why are some of my competitor's topics missing from the rows?**
The heatmap only uses topics that *your brand* tracks as the rows. If a competitor tracks a topic that your brand does not, it will not appear as a row on this matrix.

**Why didn't clicking a cell in my brand's column filter by competitor?**
Clicking a cell in your brand's own column intentionally does not add a competitor filter; it only adds the topic/prompt filter so you can see all responses for your brand on that topic. Clicking any competitor's cell adds both the competitor filter and the topic filter.

**Why does clicking Export open a pricing plan popup?**
Data exports are a premium feature. If your organization is on a free plan, clicking Export will prompt you to upgrade. The button visually looks active for everyone to allow access to the upgrade path.

**Does rearranging the columns change my exported file?**
Yes. Any column ordering or pinning you do visually on the heatmap matrix is respected and reflected in the CSV export.

**What does a value of 0.1% mean?**
To maintain visual consistency and differentiate between absolute zero (no mentions) and a tiny fraction of a mention, any calculated value between 0% and 0.1% is automatically floored and displayed as 0.1%.