run_bulk_audit
run_bulk_audit MCP tool: launch a bulk GEO Audit, one shared scan and one report per target, replayable by ref.
Updated 2026-11-06
run_bulk_audit launches a bulk GEO Audit: the questions are scanned once, then each target gets its own report from that shared scan. Each target's brand is read from its site unless you provide it.
When to use
To audit a list of prospects in the same segment. For prospects in different segments, launch one campaign per segment, or use run_geo_audit per site.
Input
| Field | Type | Default | Description |
|---|---|---|---|
targets |
object[] | required | The sites. Credits are the only limit on their number |
targets[].ref |
string | required | Your id for this target, unique in your workspace |
targets[].url |
string | required | Site, http or https. No duplicates |
targets[].brandName |
string | read from the site | Brand name |
targets[].brandDescription |
string | read from the site | What the brand does, 2,000 characters at most. Used for competitor sorting and recommendations |
targets[].aliases |
string[] | none | Other names of the brand, 10 at most. An answer that names one counts as a mention |
segmentTopic |
string | none | Segment theme, used in the recommendations |
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 |
Questions and personas are prepared from the first target with a brandDescription, otherwise from the first readable site among the first 5 targets.
Response
{
"success": true,
"created": true,
"bulkAuditId": "clx_bulk_1",
"creditsCost": 2100,
"skippedLlms": [],
"audits": [
{ "id": "clx_audit_1", "ref": "crm-1", "url": "https://a.example", "status": "PENDING", "creditsCost": 0, "shareUrl": "https://mentionable.ai/share/audit/3f9a1c7e2b6d4a10", "bulkAuditId": "clx_bulk_1", "skippedLlms": [], "failureReason": null }
]
}
created is false when these refs were already launched together. Refs already used elsewhere return ref_taken.
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: the shared scan (questions × personas × occurrences × the credits of each engine), plus a fixed amount per target (
creditsPerBulkTargetinget_audit_options), charged at launch. - Follow it:
get_bulk_auditfor the state,list_geo_auditswithfilters.bulkAuditIdfor the reports. - Own your competitors: with
reviewCompetitors: true, the campaign stops atCURATINGuntil you callselect_bulk_audit_competitors.
Related tools
- get_audit_options: engines, cost and credits before a launch.
- get_bulk_audit: follow the campaign.
- list_geo_audits: the campaign's reports.
- run_geo_audit: one site.