PendiumDocs
REST API

Trigger a Visibility Scan Preview

Kick off a fast, shareable Visibility Scan Preview for a brand — perfect for outreach links and lead-gen workflows.

POST /api/visibility/scan-preview

Authentication: Required. An account in read-only mode gets a 403 with code: "READ_ONLY" — triggering a preview scan is a write + spend, so it's refused before the scan is enqueued.

Trigger a lightweight Visibility Scan Preview — the single-shot megaprompt scan that powers the public /visibility-scan-preview/{slug} brand-page report. Designed for outbound prospecting: the GTM partner companion to Generate a Cold-Email Pitch, used to produce a polished, shareable report you can put in front of a prospect in 30–90 seconds.

This is not the right endpoint for paying customers' ongoing visibility monitoring. The Scan Preview runs once, returns a single megaprompt-derived snapshot — including the brand-tuned narrative copy (per-slide headlines and subtitles) that the report UI renders — and lives at a public URL — purpose-built for outreach. Pendium customers measuring their own brand over time use Trigger a Scan + Get a Report (managed agents, scheduled scans, full raw LLM responses, score history).

Typical use cases for the Scan Preview:

  • Cold-email outreach. Embed the returned reportUrl in an email — by the time the recipient clicks, the URL resolves to a polished /visibility-scan-preview/{brand-slug} page.
  • Lead generation. Run a report on each new lead so the GTM team has scores + analysis ready in seconds.
  • Agency / consultant prospecting. GTM partners and agencies running outbound on their own Pendium account use this endpoint to qualify and warm up a pipeline before the conversation starts.
  • In-app lead magnets. Power "scan your brand" flows that don't need to create a managed agent.

Reports complete in 30–90 seconds. Poll Get a Visibility Scan Preview for results.

Request body

{
  "url": "https://acme.com"
}
FieldTypeRequiredDefaultDescription
urlstringYes—Website URL to scan. Must be a real, active business website.
isPublicbooleanNofalse (forced)This endpoint is partner-only and partner scans are always private, so isPublic is ignored — it's always coerced to false. Passing true no longer fails; the request succeeds and the response includes a non-fatal warning field (plus Deprecation, Warning, and X-Pendium-Warning response headers). Omit the field to silence the warning. The completed report is always shared via the white-labeled partner URL (see below), never /visibility-scan-preview/{slug}.

How it works

  1. The endpoint enqueues a single-shot megaprompt LLM call against ChatGPT, Claude, Gemini, and AI Overviews to estimate visibility.
  2. It returns immediately with a uuid and reportUrl pointing at the per-UUID preview URL.
  3. Once the scan completes, the reportUrl renders the finished white-label report directly — embed it in outreach drafts immediately and it resolves by the time the recipient clicks.
  4. For local-business scans (a Yelp or Google Business Profile seed), the completed scan also builds a ready-to-launch agent site. Poll GET /api/visibility/scan-preview and read agentSiteUrl — share the prospect's site instead of (or alongside) the report. It's null for non-local-business scans and absent until the scan completes.

This endpoint is partner-only (callers without a partner team get PARTNER_SCREENNAME_REQUIRED), and partner scans are always private — isPublic is forced to false. Passing isPublic: true does not fail; the field is ignored, coerced to false, and the response carries a non-fatal warning (plus Deprecation, Warning, and X-Pendium-Warning headers, all plain ASCII) so existing integrations keep working. So reportUrl is always white-labeled: the team's verified custom domain (https://reports.youragency.com/visibility-scan-preview/<uuid>) when one is set, otherwise https://pendium.ai/partner/<slug>/visibility-scan-preview/<uuid> under the agency's branding.

Free-plan users are blocked at this endpoint with a PLAN_UPGRADE_REQUIRED error. No credits are deducted — Visibility Scan Previews are inexpensive.

Example

curl -X POST https://pendium.ai/api/visibility/scan-preview \
  -H "Content-Type: application/json" \
  -H "x-api-key: pendium_xxxxxxxxxxxx" \
  -d '{"url": "https://acme.com"}'

Response

{
  "success": true,
  "uuid": "775ba0fc-c67a-4ff2-aa0a-e1c15a638d4a",
  "status": "pending",
  "isPublic": false,
  "reportUrl": "https://pendium.ai/partner/youragency/visibility-scan-preview/775ba0fc-c67a-4ff2-aa0a-e1c15a638d4a",
  "previewUrl": "https://pendium.ai/partner/youragency/visibility-scan-preview/775ba0fc-c67a-4ff2-aa0a-e1c15a638d4a",
  "message": "Visibility Scan Preview triggered. Poll GET /api/visibility/scan-preview?uuid=… every 5-15 seconds until status='complete'."
}

If you're on the free plan:

{
  "error": "API-triggered Visibility Scan Previews require a Starter or Pro plan",
  "code": "PLAN_UPGRADE_REQUIRED",
  "currentPlan": "free",
  "upgradeUrl": "https://pendium.ai/pricing"
}

For email/SMS outreach where you don't want to pre-pay for compute on people who never click, you can skip this endpoint entirely and link recipients to:

https://pendium.ai/?report=https://acme.com

The homepage reads the ?report= param and triggers the Visibility Scan Preview on click — anonymous recipients sign in via Privy first, then land at the live in-progress report. Already-authenticated recipients are routed straight through.

Previous

Get Report

Next

Get a Visibility Scan Preview

On this page