run_geo_audit

run_geo_audit MCP tool: launch a white-label GEO Audit on one site, replayable by ref. Inputs, cost, response shape, JSON example.

Updated 2026-11-06

run_geo_audit launches a GEO Audit on one site and returns its id and share URL. It takes the same path as the audit wizard: it reads the site, generates personas and questions when you don't provide them, then starts the scans.

When to use

To audit a prospect from an agent or a CRM workflow. The call can take up to a minute because it reads the site first. The scans then run in the background: poll get_geo_audit until isComplete is true.

Input

Field Type Default Description
ref string required Your id for this request, unique in your workspace. The same ref returns the same audit without charging again
url string required Site to audit, http or https
brandName string read from the site Brand name
brandDescription string read from the site What the brand does, 2,000 characters at most. Replaces the site reading for personas, questions, competitor sorting and recommendations
aliases string[] none Other names of the brand, 10 at most. An answer that names one counts as a mention
config.llms string[] required Engine ids, from get_audit_options
config.country string FR Country of the answers (ISO 3166-1 alpha-2)
config.language string fr Language of the report
config.occurrences number 1 Runs of each question per engine, 1 to 5
config.prompts string[] generated Questions to ask, 50 at most. Omitted: generated from the site
config.promptCount number 20 Questions to generate when prompts is omitted, 1 to 20
config.personas boolean or object[] true true: ask each question as 3 to 5 personas generated from the site. A list of { name, description } (10 at most): these personas, nothing generated. Multiplies the scans
config.competitors object[] none Competitors to report, { name, domain? }, 20 at most. Kept as they are, no automatic sorting, no review. domain links the name to the way the engines write it
config.ctaId string none CTA of the shared report, from list_audit_ctas
config.teaserSections string[] [] Report sections blurred behind the CTA. Needs ctaId
config.reviewCompetitors boolean false true: pick competitors yourself. Otherwise the most cited direct competitors are kept. Ignored with competitors
config.hideUnreliableLlms boolean false Skip unstable engines at launch, leave engines under 70% of expected answers out of the report

Response

{
  "success": true,
  "created": true,
  "audit": {
    "id": "clx_audit_1",
    "ref": "crm-4821",
    "url": "https://www.example.com",
    "status": "PENDING",
    "creditsCost": 240,
    "shareUrl": "https://mentionable.ai/share/audit/3f9a1c7e2b6d4a10",
    "bulkAuditId": null,
    "skippedLlms": [],
    "failureReason": null
  }
}

created is false when this ref was already launched. skippedLlms lists the engines left out by hideUnreliableLlms.

Errors: audits_unavailable (needs an active Agency plan, audits enabled and an admin API key), credits_exhausted, invalid_llms, invalid_cta, site_unreadable, engines_unavailable, no_prompts. Each comes with a readable message.

Tips and patterns

  • Cost: questions × personas × occurrences × the credits of each engine. Personas are on by default and multiply the scans by 3 to 5. Pass personas: false to ask the questions as they are. See get_audit_options.
  • Retries are safe: resend the same ref after a timeout. A FAILED audit starts over with the same ref.
  • Own your competitors: with reviewCompetitors: true, the audit stops at REVIEWING until you call select_geo_audit_competitors.

Related tools

You can see where you stand today.

Free trial. Start tracking your AI visibility, no credit card.