Scans

A scan is one Console check. Submit it with a domain_id and optional keywords (prompts) and platforms; the credits are debited when it is accepted. The preview operation takes the same body and returns the cost without debiting. Triggering a check walks through the full flow and the request fields.

A scan's status is pending, then running, and ends as completed, failed, or cancelled. The list operation returns your 50 most recent scans, optionally filtered by domain_id. Only one scan can be pending or running per domain. Each scan carries measurement_scope, measurement_label, status, answers_total, answers_completed, answers_failed, visibility_score, brand_coverage_pct, citation_count, market_position, started_at, completed_at, duration_seconds, error_message, selected_platforms, customer_keywords, and created_at; Triggering a check describes each field.

The results operation returns what a completed check measured: headline metrics (Visibility Score, Brand Coverage, AI Mentions, and Market Position when the domain has competitors), per-platform results, the sources its answers cited, and each prompt's presence on each platform. Every number comes from that check alone. It returns 409 results_not_ready with the check's status until the check has completed, and for a check that failed or was cancelled. Read the results describes each field. The scan.completed webhook for a Console check carries the results URL as results_url.

Submitting requires an Idempotency-Key header when you authenticate with an API key; resending the same key and body returns the original response instead of charging again. Cancelling a pending scan refunds its credits; cancelling a running scan does not.

curl -X GET "https://api.surfacedby.com/api/v1/console/scans?domain_id=string&cursor=string&page_size=50" \
  -H "X-API-Key: string"

null

curl -X POST "https://api.surfacedby.com/api/v1/console/scans" \
  -H "X-API-Key: string" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "content_project_id": "string",
    "domain_id": "string",
    "keywords": [
      "string"
    ],
    "max_credits": 0,
    "platforms": [
      "string"
    ]
  }'

null

curl -X POST "https://api.surfacedby.com/api/v1/console/scans/preview" \
  -H "X-API-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "content_project_id": "string",
    "domain_id": "string",
    "keywords": [
      "string"
    ],
    "max_credits": 0,
    "platforms": [
      "string"
    ]
  }'

null

curl -X GET "https://api.surfacedby.com/api/v1/console/scans/string" \
  -H "X-API-Key: string"

null

curl -X GET "https://api.surfacedby.com/api/v1/console/scans/string/results" \
  -H "X-API-Key: string"

null

curl -X POST "https://api.surfacedby.com/api/v1/console/scans/string/cancel" \
  -H "X-API-Key: string"

null