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 (creditsPerBulkTarget in get_audit_options), charged at launch.
  • Follow it: get_bulk_audit for the state, list_geo_audits with filters.bulkAuditId for the reports.
  • Own your competitors: with reviewCompetitors: true, the campaign stops at CURATING until you call select_bulk_audit_competitors.

Related tools

You can see where you stand today.

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