scan_visibility

Trigger an AI visibility scan for a brand across ChatGPT, Claude, Gemini, and AI Overviews.

Trigger an AI visibility scan for a brand. Scans how ChatGPT, Claude, Gemini, and AI Overviews perceive and recommend the brand. Provide either a website URL (creates a new agent if needed) or a syntheticId (for existing agents).

Returns immediately — use get_scan_status to poll for results.

Authentication: Required

Parameters

Parameter	Type	Required	Default	Description
`url`	`string`	One of `url` or `syntheticId`	—	Website URL to scan. Creates a new agent if one doesn't exist for this domain.
`syntheticId`	`integer`	One of `url` or `syntheticId`	—	ID of an existing agent to re-scan.
`mode`	`"batch" \| "full"`	No	`"batch"`	Both `batch` and `full` scan all 4 AI platforms with fast, cost-effective models. (Premium-model runs are an advanced opt-in, not selected by `full` on its own.)
`maxQueries`	`integer` (1–100)	No	`30`	Total queries to run across all platforms. 20–40 recommended. Higher values give more coverage but cost more credits.
`platforms`	`string[]`	No	—	Additional enterprise-only platforms to scan alongside the standard four. Options: `Perplexity`, `Grok`, `DeepSeek`, `Qwen`, `MiniMax`, `Nemotron`, `Llama`. Requires the enterprise plan — see below.

Enterprise platforms

Every scan covers the four standard platforms (ChatGPT, Claude, Gemini, AI Overviews). Enterprise plans can broaden coverage by passing extra platforms in platforms, e.g. { "syntheticId": 1234, "platforms": ["Perplexity", "Grok"] }.

If your account isn't on the enterprise plan, the requested enterprise platforms are skipped (the scan still runs on the standard four) and the response includes a droppedEnterprisePlatforms array plus an enterpriseNotice explaining what was skipped. Contact sales to enable them.

Behavior

Scanning an existing agent

When you provide a syntheticId:

Ownership is verified against your API key.
Credit balance is checked — returns an error if insufficient.
If a scan is already running, returns current progress instead of starting a new one.
Otherwise, triggers the scan and returns immediately.

Scanning a new URL

When you provide a url:

The domain is extracted from the URL.
If an agent already exists for that domain under your account, it re-scans the existing agent.
If no agent exists, a new brand agent is created and the scan begins.
The agent initialization includes website scraping, knowledge base creation, and the visibility scan.

Response

{
  "success": true,
  "syntheticId": 1234,
  "agentName": "Example",
  "scanTriggered": true,
  "isNewAgent": false,
  "mode": "batch",
  "maxQueries": 30,
  "message": "Scan triggered. Use get_scan_status to poll for results (every 30-60 seconds)."
}

Error: insufficient credits

{
  "success": false,
  "error": "Insufficient credits",
  "creditBalance": 0,
  "upgradeUrl": "https://pendium.ai/pricing"
}

Scan already running

{
  "success": true,
  "scanAlreadyRunning": true,
  "syntheticId": 1234,
  "progress": {
    "completedQueries": 12,
    "totalQueries": 30
  },
  "message": "Scan already in progress: 12/30 queries complete. Use get_scan_status to poll."
}

On this page