Trigger a Scan

POST /api/visibility/scan

Authentication: Required

Start a visibility scan that checks how AI platforms perceive and recommend a brand. You can scan a new URL (which creates a brand agent if one doesn't exist) or re-scan an existing agent by ID.

The scan runs in the background — this endpoint returns immediately. Use Poll Scan Status to check when results are ready.

Request body

{
  "url": "https://example.com",
  "mode": "batch",
  "maxQueries": 30
}

How it works

Scanning an existing agent (syntheticId):

1. Verifies you own the agent
2. Checks your credit balance
3. If a scan is already running, returns its progress instead of starting a new one
4. Otherwise, kicks off the scan and returns immediately

Scanning a new URL (url):

1. Extracts the domain from your URL
2. Checks if you already have an agent for that domain — if so, re-scans it
3. If not, creates a new brand agent (scrapes the site, builds a knowledge base) and starts the scan

Example

curl -X POST https://pendium.ai/api/visibility/scan \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_xxxxxxxxxxxx" \
  -d '{"url": "https://example.com", "mode": "batch", "maxQueries": 30}'

Response

{
  "success": true,
  "syntheticId": 1234,
  "agentName": "Example",
  "scanTriggered": true,
  "isNewAgent": false,
  "mode": "batch",
  "maxQueries": 30,
  "message": "Scan triggered. Poll GET /api/visibility/scan?syntheticId=1234 for results."
}

If a scan is already running:

{
  "success": true,
  "scanAlreadyRunning": true,
  "syntheticId": 1234,
  "progress": {
    "completedQueries": 12,
    "totalQueries": 30
  }
}

If you're out of credits:

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