Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

fix(prompts): count each keyword once in Similar Topics and retune High Opportunity (#1104)

Cihan071599750bd5
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/page.tsx
index 8fd7b1f5a..60ae88226 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/page.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/page.tsx
@@ -144,6 +144,11 @@ import { getPromptUsage, isPromptLimitReached } from '@/lib/prompt-usage';
import { getTopics } from '@/lib/actions/topic';
import type { PromptVisibilitySummary } from '@/lib/actions/tracking';
import { aggregatePromptVolumeClusters } from '@/lib/prompt-volume-clusters';
+import {
+ OPPORTUNITY_HIGH_VOLUME,
+ OPPORTUNITY_MIN_VOLUME,
+ opportunityLevel,
+} from '@/lib/prompt-volume-opportunity';
import type { PromptVolume, Prompt, Topic } from '@/types';
import { toast } from 'sonner';
import {
@@ -1681,7 +1686,10 @@ export default function PromptsPage() {
const totalGoogleVol = volumes.reduce((s, v) => s + v.totalGoogleVolume, 0);
const totalAiVol = volumes.reduce((s, v) => s + v.estAiVolume, 0);
- const totalKeywords = volumes.reduce((s, v) => s + v.keywords.length, 0);
+ // Distinct keywords: prompts share many, as Similar Topics counts them.
+ const totalKeywords = new Set(
+ volumes.flatMap((v) => v.keywords.map((k) => k.trim().toLowerCase())),
+ ).size;
const filtered = volumes.filter(
(v) =>
@@ -2145,7 +2153,7 @@ export default function PromptsPage() {
<KpiCard
title="Avg. AI Volume"
icon={BarChart3}
- value={`~${formatCompactNumber(totalAiVol / volumes.length)}`}
+ value={`~${formatCompactNumber(Math.round(totalAiVol / volumes.length))}`}
sub="per prompt"
/>
</div>
@@ -2266,15 +2274,16 @@ export default function PromptsPage() {
)}
<div className="px-6 py-2 border-t">
<p className="text-xs text-muted-foreground">
- * Est. AI Volume = Total Google search volume of extracted keywords × AI
- adoption rate. Figures are approximations for planning purposes.
+ * Est. AI Volume = the median Google search volume of the prompt&apos;s
+ extracted keywords × AI adoption rate. Figures are approximations for planning
+ purposes.
</p>
</div>
</CardContent>
</Card>
{/* High Opportunity Prompts */}
- {volumes.filter((v) => v.estAiVolume >= 5000).length > 0 && (
+ {volumes.some((v) => opportunityLevel(v.estAiVolume)) && (
<Card>
<CardHeader className="pb-2">
<div className="flex items-center gap-2">
@@ -2303,7 +2312,7 @@ export default function PromptsPage() {
</ColHead>
<ColHead
className="text-right pr-6"
- tooltip="Opportunity level based on estimated AI volume. High = above 10k/mo, Medium = 5k–10k/mo."
+ tooltip={`Opportunity level based on estimated AI volume. High = ${formatCompactNumber(OPPORTUNITY_HIGH_VOLUME)}+/mo, Medium = ${formatCompactNumber(OPPORTUNITY_MIN_VOLUME)}–${formatCompactNumber(OPPORTUNITY_HIGH_VOLUME)}/mo.`}
>
Opportunity
</ColHead>
@@ -2311,7 +2320,7 @@ export default function PromptsPage() {
</TableHeader>
<TableBody>
{volumes
- .filter((v) => v.estAiVolume >= 5000)
+ .filter((v) => opportunityLevel(v.estAiVolume))
.sort((a, b) => b.estAiVolume - a.estAiVolume)
.map((row) => (
<TableRow key={row.id} className="hover:bg-muted/50">
@@ -2334,12 +2343,12 @@ export default function PromptsPage() {
variant="outline"
className={cn(
'text-xs',
- row.estAiVolume >= 10000
+ opportunityLevel(row.estAiVolume) === 'high'
? 'border-red-500/30 bg-red-500/10 text-red-600 dark:text-red-400'
: 'border-amber-500/30 bg-amber-500/10 text-amber-600 dark:text-amber-400',
)}
>
- {row.estAiVolume >= 10000 ? 'High' : 'Medium'}
+ {opportunityLevel(row.estAiVolume) === 'high' ? 'High' : 'Medium'}
</Badge>
</TableCell>
</TableRow>
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/similar-topics/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/similar-topics/page.tsx
index 6b3aa460e..62ac63139 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/similar-topics/page.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/similar-topics/page.tsx
@@ -115,7 +115,7 @@ export default function SimilarTopicsPage() {
<div className="text-2xl font-semibold tabular-nums">
{formatCompactNumber(totals.googleVolume)}
</div>
- <p className="text-xs text-muted-foreground">monthly searches</p>
+ <p className="text-xs text-muted-foreground">monthly searches, across prompts</p>
</CardContent>
</Card>
<Card>
@@ -126,7 +126,7 @@ export default function SimilarTopicsPage() {
<div className="text-2xl font-semibold tabular-nums">
{formatCompactNumber(totals.aiVolume)}
</div>
- <p className="text-xs text-muted-foreground">monthly AI queries</p>
+ <p className="text-xs text-muted-foreground">monthly AI queries, across prompts</p>
</CardContent>
</Card>
</div>
diff --git a/web/src/lib/mcp/data.ts b/web/src/lib/mcp/data.ts
index dfe507a50..93d246a84 100644
--- a/web/src/lib/mcp/data.ts
+++ b/web/src/lib/mcp/data.ts
@@ -2028,7 +2028,8 @@ const PROMPT_VOLUMES_MAX_LIMIT = 500;
/**
* Return per-prompt search-volume + competition rows for a brand, scoped
* `brand → prompt_sets → prompts → prompt_volumes`. Surfaces the demand
- * (`total_google_volume` / `est_ai_volume`) and competition meter
+ * (`total_google_volume`, the median of the keywords' volumes, and
+ * `est_ai_volume`) and competition meter
* (`competition_index` / `competition`, see #44) so callers can answer
* "which prompts have the most demand / the least competition?".
*
diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.ts
index 2c82ebc80..2542f0fee 100644
--- a/web/src/lib/mcp/server.ts
+++ b/web/src/lib/mcp/server.ts
@@ -714,7 +714,7 @@ export function createMcpServer(auth: McpAuthContext): McpServer {
'get_prompt_volumes',
{
description:
- 'Get per-prompt search demand and competition for a brand. Returns one row per analyzed prompt with its keywords, Google search volumes, total_google_volume, est_ai_volume (estimated AI search demand), competition_index (0-100), and competition label (LOW / MEDIUM / HIGH). Sorted by est_ai_volume descending. Use this for "which prompts have the most demand?" or "which prompts have the least competition?" prioritization questions. Only returns prompts that already have volume analysis — triggering a new analysis is not available here.',
+ 'Get per-prompt search demand and competition for a brand. Returns one row per analyzed prompt with its keywords, the Google search volume of each keyword, total_google_volume (the Google volume of the prompt: the median of its keyword volumes, not their sum), est_ai_volume (estimated AI search demand: total_google_volume × the AI adoption rate), competition_index (0-100), and competition label (LOW / MEDIUM / HIGH). Sorted by est_ai_volume descending. Use this for "which prompts have the most demand?" or "which prompts have the least competition?" prioritization questions. Only returns prompts that already have volume analysis — triggering a new analysis is not available here.',
inputSchema: {
brand_id: relaxedUuid.describe('Brand UUID, from list_brands.'),
limit: z
diff --git a/web/src/lib/prompt-volume-clusters.test.ts b/web/src/lib/prompt-volume-clusters.test.ts
new file mode 100644
index 000000000..d5768f99b
--- /dev/null
+++ b/web/src/lib/prompt-volume-clusters.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import type { PromptVolume } from '@/types';
+import { aggregatePromptVolumeClusters } from './prompt-volume-clusters';
+
+const prompt = (
+ id: string,
+ keywords: string[],
+ googleVolumes: Record<string, number>,
+ totalGoogleVolume: number,
+): PromptVolume => ({
+ id: `v-${id}`,
+ promptId: id,
+ promptText: `prompt ${id}`,
+ promptCategory: '',
+ intent: 'how-to',
+ keywords,
+ googleVolumes,
+ totalGoogleVolume,
+ aiVolumeMultiplier: 0.15,
+ estAiVolume: Math.round(totalGoogleVolume * 0.15),
+ competitionIndex: null,
+ competition: null,
+ fetchedAt: '2026-10-16T00:00:00Z',
+});
+
+describe('aggregatePromptVolumeClusters', () => {
+ it("counts a keyword's volume once however many prompts share it", () => {
+ const clusters = aggregatePromptVolumeClusters([
+ prompt('a', ['seo tools', 'ai seo'], { 'seo tools': 110000, 'ai seo': 8100 }, 59050),
+ prompt(
+ 'b',
+ ['seo tools', 'rank checker'],
+ { 'seo tools': 110000, 'rank checker': 1900 },
+ 55950,
+ ),
+ ]);
+
+ const seoTools = clusters.find((c) => c.keyword === 'seo tools')!;
+ expect(seoTools.volume).toBe(110000);
+ expect(seoTools.estimatedAiVolume).toBe(16500);
+ expect(seoTools.occurrences).toBe(2);
+ // Biggest search first.
+ expect(clusters.map((c) => c.keyword)).toEqual(['seo tools', 'ai seo', 'rank checker']);
+ });
+
+ it("finds a keyword's volume whatever its case", () => {
+ const [cluster] = aggregatePromptVolumeClusters([
+ prompt('a', ['Best CRM Software'], { 'best crm software': 500 }, 500),
+ ]);
+ expect(cluster.volume).toBe(500);
+ });
+
+ it('counts a prompt that lists a keyword twice once', () => {
+ const [cluster] = aggregatePromptVolumeClusters([
+ prompt('a', ['CRM', 'crm'], { crm: 100 }, 100),
+ ]);
+ expect(cluster.occurrences).toBe(1);
+ expect(cluster.prompts).toHaveLength(1);
+ });
+
+ it("lists each prompt with the prompt's own volumes", () => {
+ const [cluster] = aggregatePromptVolumeClusters([
+ prompt(
+ 'a',
+ ['seo tools', 'ai seo', 'serp tracker'],
+ { 'seo tools': 110000, 'ai seo': 8100, 'serp tracker': 1300 },
+ 8100,
+ ),
+ ]);
+ expect(cluster.prompts[0]).toMatchObject({ id: 'a', volume: 8100, estimatedAiVolume: 1215 });
+ });
+});
diff --git a/web/src/lib/prompt-volume-clusters.ts b/web/src/lib/prompt-volume-clusters.ts
index a9d37e2d2..1c73718fb 100644
--- a/web/src/lib/prompt-volume-clusters.ts
+++ b/web/src/lib/prompt-volume-clusters.ts
@@ -2,9 +2,12 @@ import type { PromptVolume } from '@/types';
export interface PromptVolumeCluster {
keyword: string;
+ /** The keyword's monthly Google volume, counted once. */
volume: number;
estimatedAiVolume: number;
+ /** How many prompts use the keyword. */
occurrences: number;
+ /** Those prompts, each with its own volumes (the prompt's, not the keyword's). */
prompts: {
id: string;
text: string;
@@ -14,44 +17,53 @@ export interface PromptVolumeCluster {
}[];
}
+/**
+ * A row per keyword (case-folded) across the brand's analyzed prompts.
+ *
+ * A keyword's volume is the demand for that one search, so it counts once
+ * however many prompts share it. It used to be added again for every prompt,
+ * so "seo tools" (110k a month) in 121 prompts read 13.1M. A prompt that lists
+ * a keyword twice counts once, and a keyword's volume is found whatever its
+ * case: google_volumes keeps the provider's spelling of each keyword.
+ */
export function aggregatePromptVolumeClusters(volumes: PromptVolume[]): PromptVolumeCluster[] {
const merged = new Map<string, PromptVolumeCluster>();
for (const v of volumes) {
+ const volumeOf = new Map(
+ Object.entries(v.googleVolumes).map(([kw, n]) => [kw.trim().toLowerCase(), n]),
+ );
+ const prompt = {
+ id: v.promptId,
+ text: v.promptText,
+ intent: v.intent,
+ volume: v.totalGoogleVolume,
+ estimatedAiVolume: v.estAiVolume,
+ };
+ const seen = new Set<string>();
+
for (const kw of v.keywords) {
const normalized = kw.trim().toLowerCase();
- if (!normalized) continue;
+ if (!normalized || seen.has(normalized)) continue;
+ seen.add(normalized);
- const volume = v.googleVolumes[kw] ?? 0;
- const estimatedAiVolume = Math.round(volume * v.aiVolumeMultiplier);
+ const volume = volumeOf.get(normalized) ?? 0;
const existing = merged.get(normalized);
-
if (existing) {
- existing.volume += volume;
- existing.estimatedAiVolume += estimatedAiVolume;
+ // The same search has one volume; a prompt that missed it reads 0.
+ if (volume > existing.volume) {
+ existing.volume = volume;
+ existing.estimatedAiVolume = Math.round(volume * v.aiVolumeMultiplier);
+ }
existing.occurrences += 1;
- existing.prompts.push({
- id: v.promptId,
- text: v.promptText,
- intent: v.intent,
- volume,
- estimatedAiVolume,
- });
+ existing.prompts.push(prompt);
} else {
merged.set(normalized, {
keyword: kw,
volume,
- estimatedAiVolume,
+ estimatedAiVolume: Math.round(volume * v.aiVolumeMultiplier),
occurrences: 1,
- prompts: [
- {
- id: v.promptId,
- text: v.promptText,
- intent: v.intent,
- volume,
- estimatedAiVolume,
- },
- ],
+ prompts: [prompt],
});
}
}
diff --git a/web/src/lib/prompt-volume-opportunity.test.ts b/web/src/lib/prompt-volume-opportunity.test.ts
new file mode 100644
index 000000000..39d5e0016
--- /dev/null
+++ b/web/src/lib/prompt-volume-opportunity.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { opportunityLevel } from './prompt-volume-opportunity';
+
+describe('opportunityLevel', () => {
+ it('leaves a prompt under 1,500 AI searches a month off the list', () => {
+ expect(opportunityLevel(0)).toBeNull();
+ expect(opportunityLevel(1499)).toBeNull();
+ });
+
+ it('calls 1,500 to 2,999 Medium and 3,000 or more High', () => {
+ expect(opportunityLevel(1500)).toBe('medium');
+ expect(opportunityLevel(2999)).toBe('medium');
+ expect(opportunityLevel(3000)).toBe('high');
+ expect(opportunityLevel(3645)).toBe('high');
+ });
+});
diff --git a/web/src/lib/prompt-volume-opportunity.ts b/web/src/lib/prompt-volume-opportunity.ts
new file mode 100644
index 000000000..8e955163a
--- /dev/null
+++ b/web/src/lib/prompt-volume-opportunity.ts
@@ -0,0 +1,19 @@
+/**
+ * Insights' High Opportunity Prompts: a prompt makes the list from
+ * OPPORTUNITY_MIN_VOLUME estimated AI searches a month, and is High rather
+ * than Medium from OPPORTUNITY_HIGH_VOLUME.
+ *
+ * Set for the median-based estimate at the 45% AI adoption rate (00154,
+ * 00155). The old 5k and 10k suited the sum of five keywords at 15%: on the
+ * largest brand the median prompt now reads ~1.6k (it was ~4.7k), and p90
+ * ~6.7k (~41k). These keep roughly the same share of prompts on the list,
+ * about half, with the top third or so High.
+ */
+export const OPPORTUNITY_MIN_VOLUME = 1500;
+export const OPPORTUNITY_HIGH_VOLUME = 3000;
+
+export function opportunityLevel(estAiVolume: number): 'high' | 'medium' | null {
+ if (estAiVolume >= OPPORTUNITY_HIGH_VOLUME) return 'high';
+ if (estAiVolume >= OPPORTUNITY_MIN_VOLUME) return 'medium';
+ return null;
+}
diff --git a/web/src/types/index.ts b/web/src/types/index.ts
index 866cec0c2..bf0e15e0e 100644
--- a/web/src/types/index.ts
+++ b/web/src/types/index.ts
@@ -163,9 +163,15 @@ export interface PromptVolume {
promptCategory: string;
intent: string;
keywords: string[];
+ /** Each keyword's monthly Google volume, under the provider's spelling. */
googleVolumes: Record<string, number>;
+ /**
+ * The prompt's monthly Google volume: the median of its keywords that have
+ * one (00154). Named before the median replaced their sum.
+ */
totalGoogleVolume: number;
aiVolumeMultiplier: number;
+ /** totalGoogleVolume × aiVolumeMultiplier, rounded. */
estAiVolume: number;
competitionIndex: number | null;
competition: 'LOW' | 'MEDIUM' | 'HIGH' | null;