@mentionflow/sdk

Your AI-visibility data, in code. How ChatGPT, Perplexity, Gemini, Google AI Overviews and Claude talk about your brand, pulled from the MentionFlow v1 REST API with a typed, zero-dependency client.

The API and the MentionFlow dashboard run the same code, so a number from this SDK and the number on your screen can never disagree. Read access works on every plan. Create a key under Settings → API keys and you're in.

Install

npm install @mentionflow/sdk

Works in Node 18+, Bun, Deno, and edge runtimes. Anywhere with fetch.

30-second start

import { MentionFlow } from "@mentionflow/sdk";

const mf = new MentionFlow({ key: process.env.MENTIONFLOW_KEY! });

const { brands } = await mf.brands();
const overview = await mf.overview({ brand: brands[0].id });
console.log(overview);

Reads

Every method maps 1:1 onto a v1 endpoint and returns the server's response untouched:

await mf.overview({ brand });        // the visibility scorecard
await mf.prompts({ brand });         // tracked prompts + tag groups
await mf.competitors({ brand });
await mf.sources({ brand });         // cited domains
await mf.urls({ brand });            // URL-level citations
await mf.answers({ brand });         // raw stored answers, newest first
await mf.shopping({ brand });        // AI shopping leaderboard (Growth+)
await mf.shoppingTrend({ brand });
await mf.factCheck({ brand });       // cached knowledge-base audit
await mf.ads({ brand, days: 28 });   // captured advertiser units
await mf.sentiment({ brand });       // tone per entity + engine, with receipts
await mf.crawlers({ brand, days: 7 }); // agent analytics (Growth+)

Metrics history

The daily series behind the dashboard charts:

const history = await mf.metricsHistory({
  metric: "visibility",           // or share_of_voice_fraction | citation_share | sentiment_index
  brand,
  days: 28,                        // or { from: "2026-07-01", to: "2026-07-28" }
  engine: ["chatgpt", "gemini"],  // optional; default is the blended scope
  competitors: true,               // optional competitor series
});

Days with no collection come back as honest nulls with sample_size 0. The API never makes up a zero.

Pagination

The list resources (brands, prompts, competitors, sources, urls, answers) support keyset pagination. The async iterator follows next_cursor to the end for you:

for await (const answer of mf.paginate("answers", { brand, limit: 200 })) {
  process(answer);
}

Ingest (crawler analytics)

Ship server or CDN log lines, nginx/apache combined format or NDJSON. The server ignores non-AI traffic, so unfiltered logs are fine:

await mf.sendCrawlerEvents(logText, { brand });

Works with full-scope and ingest-scope keys. For Next.js sites, prefer @mentionflow/vercel: it reports automatically from middleware.

Errors and rate limits

Non-2xx responses throw MentionFlowError with status, the server's message, the parsed body, and retryAfter (seconds) on 429. Your key's bucket is 120 requests per minute. The latest X-RateLimit-* headers are on mf.lastRateLimit.

import { MentionFlowError } from "@mentionflow/sdk";

try {
  await mf.overview({ brand });
} catch (err) {
  if (err instanceof MentionFlowError && err.status === 429) {
    await sleep((err.retryAfter ?? 30) * 1000);
  } else throw err;
}

Self-hosted

const mf = new MentionFlow({ key, baseUrl: "https://mf.example.com" });

Security notes

• The API key belongs server-side. Don't ship it to browsers.
• Use a dedicated key per integration so you can revoke it independently (Settings → API keys).