get_bulk_audit

get_bulk_audit fetches one bulk GEO Audit campaign by id: where it sits in its lifecycle, how many targets sit in each status, and, once COMPLETED, the segment-level recommendations and content ideas mutualised across every target report.

When to use

Use it to poll a campaign you triggered, to know whether it is waiting on you (CURATING), and to read the segment insights once it is done. It is the bulk counterpart of get_geo_audit.

Input

Response

In progress

{
  "success": true,
  "bulkAuditId": "clx_bulk_42",
  "status": "CURATING",
  "segmentTopic": "Plumbers in Lyon",
  "label": "Plumbers in Lyon",
  "targetCount": 12,
  "targetsByStatus": { "SCANNING": 12 },
  "progress": { "received": 120, "expected": 120 },
  "createdAt": "2026-09-14T09:12:00.000Z",
  "isComplete": false,
  "message": "Scans done. The campaign is paused at competitor curation — call select_bulk_audit_competitors before insights can be generated."
}

Completed

{
  "success": true,
  "bulkAuditId": "clx_bulk_42",
  "status": "COMPLETED",
  "targetCount": 12,
  "targetsByStatus": { "COMPLETED": 12 },
  "isComplete": true,
  "country": "FR",
  "language": "fr",
  "llms": ["CHATGPT", "PERPLEXITY"],
  "occurrences": 1,
  "creditsCost": 420,
  "personas": [{ "id": "p1", "name": "Homeowner" }],
  "selectedCompetitors": ["Acme", "Globex"],
  "recommendations": [{ "category": "content", "severity": "important", "title": "Publish city pages" }],
  "contentIdeas": [{ "title": "How to pick a plumber in Lyon", "angle": "buyer guide" }],
  "insightsGeneratedAt": "2026-09-15T08:40:00.000Z",
  "completedAt": "2026-09-15T08:41:00.000Z",
  "message": "Per-target metrics and report URLs: list_geo_audits({ filters: { bulkAuditId } }), then get_geo_audit on any target."
}

Not found

{ "success": false, "error": "bulk_audit_not_found", "message": "No bulk campaign with this id exists in your workspace. Verify the bulkAuditId returned by list_bulk_audits." }

Field notes:

• The targets are not returned here. A campaign can hold hundreds of them, so the list is paginated by list_geo_audits({ filters: { bulkAuditId } }). What you get instead is targetCount plus targetsByStatus, a headcount per target status.
• country and language are stored on the targets, not on the parent, so they are read off the campaign's first target.
• recommendations and contentIdeas are segment-level: generated once at campaign completion and reused by every target's share report.

Tips and patterns

• Branch on status, not on isComplete alone. CURATING means the campaign is waiting for select_bulk_audit_competitors; the message field spells out the next step for every in-progress status.
• Use targetsByStatus as a cheap progress bar instead of paging the whole target list just to count.
• Then drill down. list_geo_audits({ filters: { bulkAuditId, status: ["COMPLETED"] } }) gives the finished targets with their reportUrl; get_geo_audit gives one target's metrics.

Related tools

• list_bulk_audits: find the campaign id.
• list_geo_audits: page the campaign's targets.
• select_bulk_audit_competitors: unblock a campaign stuck at CURATING.