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: falseto ask the questions as they are. Seeget_audit_options. - Retries are safe: resend the same
refafter a timeout. AFAILEDaudit starts over with the sameref. - Own your competitors: with
reviewCompetitors: true, the audit stops atREVIEWINGuntil you callselect_geo_audit_competitors.
Related tools
- get_audit_options: engines, cost and credits before a launch.
- get_geo_audit: follow the audit, then read the report.
- run_bulk_audit: many sites, one shared scan.
- create_audit_cta: the CTA of the shared report.