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"`	`batch`: all 4 AI platforms with cost-effective models. `full`: premium models for highest accuracy.
`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.

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."
}