Measurement API
The Measurement API is the REST interface to everything MentionBeat records: visibility scores, sampled answers, citations and fix-queue findings, ready to pull into your own stack. Every endpoint below is generated from the OpenAPI spec, so a client you generate stays in sync.
Loading the OpenAPI specification…
Authentication — send your org API key in the
X-API-Key header
(or
Authorization: Bearer <key>). Base URL:
…
· Raw spec:
openapi.json
Prefer tools over raw HTTP? The same data is exposed to MCP clients via the
MCP server below.
Rate limits — 600 requests a minute per API key.
Over it, you get a 429 with a Retry-After header; back off
that many seconds and continue. Real dashboards and connectors sit far under this.
MCP server
Use MentionBeat from Claude, Claude Code, or any MCP client — read your measurement data
and work the action queue without leaving your editor.
Install — the package is on npm, so one command adds it to Claude Code
(for other clients, put the same
npx line in
claude_desktop_config.json /
.mcp.json):
claude mcp add mentionbeat \
--env MENTIONBEAT_API_KEY=<your org API key> \
-- npx -y @mentionbeat/mcp-server
# equivalent JSON for any MCP client
{
"mcpServers": {
"mentionbeat": {
"command": "npx",
"args": ["-y", "@mentionbeat/mcp-server"],
"env": { "MENTIONBEAT_API_KEY": "<your org API key>" }
}
}
}
The key comes from Settings → API keys and is exchanged for a short-lived token behind
the scenes, so nothing permanent travels to the measurement API. Every call is scoped to what you can
already see and do. Self-hosting? PLATFORM_URL,
MEASURE_API_URL and STUDIO_URL point it at your
own deployment.
Ship your access logs — see which AI bots read you
GPTBot, ClaudeBot, PerplexityBot and friends fetch your pages before an engine can cite them.
POST /v1/crawler/ingest takes access-log lines and keeps only the AI-bot hits,
attributed to your tracked products. The fastest way to feed it is a Cloudflare Worker on your zone —
copy, set two values, deploy:
Cloudflare Worker — passthrough proxy; AI-bot hits are reported after the response is served,
so it adds zero latency for your visitors:
// wrangler secret put MENTIONBEAT_API_KEY (a key from Settings → API keys)
// Route: yourdomain.com/*
const AI_UA = /(GPTBot|OAI-SearchBot|ChatGPT|Claude|anthropic|Perplexity|Google-Extended|GoogleOther|Bytespider|Meta-ExternalAgent|FacebookBot|Applebot|Amazonbot|CCBot|cohere|DuckAssistBot|YouBot|PetalBot|Diffbot|Timpibot|MistralAI)/i;
export default {
async fetch(request, env, ctx) {
const response = await fetch(request);
const ua = request.headers.get("user-agent") || "";
if (AI_UA.test(ua)) {
ctx.waitUntil(fetch("https://api.mentionbeat.com/v1/crawler/ingest", {
method: "POST",
headers: { "content-type": "application/json", "x-api-key": env.MENTIONBEAT_API_KEY },
body: JSON.stringify({ hits: [{
user_agent: ua,
path: new URL(request.url).pathname,
status: response.status,
timestamp: new Date().toISOString(),
}] }),
}).catch(() => {}));
}
return response;
},
};
The regex is a coarse prefilter so ordinary visitor traffic never leaves your edge — exact bot detection
(vendor, purpose: training vs live answers vs search) happens server-side against the maintained registry.
Not on Cloudflare? Any log shipper works: batch up to 5,000 lines per request with
user_agent + path per line. CSV import from your
server logs is also in the Studio's measure panel.
Tools
| Tool | What it does | Writes? |
|---|
list_projects | Every brand/product being tracked. | — |
get_project | One project: prompt counts, runs, latest run id. | — |
list_runs | Measurement runs, newest first, with actual cost. | — |
get_run_metrics | Every metric with its 95% CI and sample size. | — |
get_citations | Domains the engines cited, classified own/rival/third-party. | — |
get_benchmark | You vs the field: mention share and rank. | — |
get_hallucinations | Engine claims that contradict your approved facts. | — |
get_trends | Headline metrics over time, with noise-aware deltas. | — |
get_experiments | Measured lift from a specific content change. | — |
list_actions | The work queue: what to fix, ranked, with evidence. | — |
get_fix | Paste-ready JSON-LD / FAQ / intro for one page. | — |
check_ai_access | Whether AI crawlers can actually reach a site. | — |
run_site_audit | Crawl + audit a site, adding findings to the queue. | yes |
mark_action_fixed | Mark an item fixed — triggers an immediate re-check. | yes |
verify_actions | Re-check everything marked fixed. | yes |
The loop this makes possible. Ask your assistant to "fix my top three visibility
findings": it calls list_actions, pulls the exact markup with
get_fix, applies it in your repo, then calls
mark_action_fixed — which re-audits the live page and reports back whether the
finding is genuinely gone. A fix that didn't land comes back as not cleared, with the reason, and
the item returns to the queue. The assistant never gets to mark its own homework.