list_geo_audits

list_geo_audits MCP tool: list GEO Audits (one-shot white-label audits) for the workspace with status, prospect URL and progress, newest first.

Updated 2026-10-08

list_geo_audits returns the GEO Audits (one-shot white-label audits) for the workspace, newest first. Each row carries the status, the audited prospect URL, the brand name, the target country and language, the selected LLMs and a progress counter. Unlike page fixes, GEO Audits are workspace-scoped, not tied to a single project, so this tool takes no projectId.

When to use

  • For agencies producing many audits via the MCP: list the whole workspace and read the state of every audit without opening the UI.
  • To find audits stuck at competitor selection (filter with filters.status: ["REVIEWING"]) before they can move to insight generation.
  • To group a batch: pass filters.bulkAuditId to get one campaign's targets, filters.scope to include (or isolate) campaign targets across every campaign, or filters.dateRange to pull back the audits launched in a given window.
  • To track which audits have reached COMPLETED and are ready to read with get_geo_audit.

This tool lists the one-shot GEO Audits only. It does not return page fixes, which belong to a project: read one with get_page_fix.

Input

Field Type Default Description
cursor string - Cursor returned in pageInfo.nextCursor.
limit int 20 Max items, 1–100.
filters.status enum[] - Any of PENDING, SCANNING, REVIEWING, GENERATING, COMPLETED, FAILED. Omit to return all.
filters.dateRange { from?, to? } - Filters on createdAt. Date (2026-09-01) or ISO datetime.
filters.bulkAuditId string (CUID) - Returns that bulk campaign's targets instead of single audits.
filters.scope single | bulk_children | all single Which audits to consider: standalone audits only, campaign targets across every campaign, or both. Ignored when bulkAuditId is set.

Without filters.bulkAuditId, the tool returns single audits only, mirroring the list shown in the app; a campaign's children are never mixed in. Widen that with filters.scope. filters.status applies in every case, so scope: "bulk_children" with status: ["COMPLETED"] returns every finished campaign target of the workspace.

Response

{
  "data": [
    {
      "id": "clx_audit_42",
      "prospectUrl": "https://prospect.com",
      "domain": "prospect.com",
      "brandName": "Prospect",
      "status": "REVIEWING",
      "country": "US",
      "language": "en",
      "llms": ["CHATGPT", "PERPLEXITY"],
      "creditsCost": 24,
      "shareSlug": "prospect-9f3a",
      "reportUrl": "https://mentionable.ai/share/audit/prospect-9f3a",
      "bulkAuditId": null,
      "bulkLabel": null,
      "progress": { "received": 6, "expected": 24 },
      "createdAt": "2026-06-20T09:00:00.000Z",
      "completedAt": null
    }
  ],
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": 1 }
}

Field notes:

  • domain is the prospect host without protocol, www. or trailing slash. It is the join key for an external prospect base, so you never clean up prospectUrl at import time.
  • reportUrl is absolute: the workspace's own domain in white-label, mentionable.ai otherwise. Prefer it over rebuilding a URL from shareSlug.
  • bulkAuditId and bulkLabel are set on the targets of a bulk campaign (bulkLabel is the campaign's inferred segment topic) and null on single audits.
  • status follows the GEO Audit lifecycle: PENDING (created, scan not started), SCANNING (LLM scans running), REVIEWING (scans done, paused for competitor selection), GENERATING (competitors picked, insights being written), COMPLETED (frozen, report ready), or FAILED (no engine returned enough answers).
  • progress.received / progress.expected count scan results. They let you estimate how far a SCANNING audit is from REVIEWING.
  • completedAt is null until the audit reaches COMPLETED.

Tips and patterns

  • Pagination: the cursor is the audit's id. Stable across page boundaries.
  • Pair with get_geo_audit: this tool returns metadata only. To read the recommendations, content ideas and selected competitors, call get_geo_audit with the id.
  • Group without guessing: filters.bulkAuditId replaces regrouping a batch by createdAt window. On single audits launched one by one, filters.dateRange does the same job.
  • Sweep every report at once: filters.scope: "all" plus a status filter is the one call that covers single audits and campaign targets together, e.g. to collect every COMPLETED report URL of the workspace.
  • Watch for REVIEWING: an audit parked at REVIEWING waits for a human (or an agent) to confirm competitors. Surface these so they don't stall silently.

Related tools

  • get_geo_audit: fetch a single GEO Audit (full content when COMPLETED).
  • get_page_fix: the fix of one page of a tracked project, a different object.

You can see where you stand today.

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