Scans
Browse a domain's check history and fetch one check.
A scan is one check run for a domain: a Daily Check or a Full Check. Listing scans returns the domain's history, most recently started first. Fetching one scan returns the same summary object; per-answer results are not part of these endpoints, and the analytics endpoint reads a specific check when you pass its id as scan_id.
Checks run on your plan's schedule; the Data API cannot start one. On-demand checks are available through the Console API. Both endpoints here are read-only and available on Professional and Agency.
Scan object
| Field | Description |
|---|---|
id | Scan id. Pass it as scan_id to the analytics endpoint. |
domain_id | The tracked domain. |
measurement_scope | daily_monitoring for a Daily Check, full_benchmark for a Full Check. |
measurement_label | Daily Check or Full Check. |
status | The check's state: pending, running, completed, failed, or cancelled. |
answers_total | Answers the check planned to collect: one per prompt and AI platform. |
answers_completed, answers_failed | Answers collected so far, and answers that could not be collected. |
citation_count | Number of citations recorded in the check. |
brand_coverage_pct | Brand Coverage for the check, as a percentage. |
visibility_score | Visibility Score for the check (0 to 100). |
market_position | Market Position for the check (1 is first). |
started_at, completed_at | When the check started and finished. |
duration_seconds | How long the check ran. |
error_message | Why the check stopped, set when it failed or was cancelled; otherwise null. |
error_message is always one of a fixed set of messages, where example.com stands for the domain name (or "that website"):
We could not finish this check.(any failure without a more specific message)This check was cancelled.This check stopped because the domain was removed.This check stopped because the account was deleted.This check stopped because the plan no longer includes checks.This check waited in the queue too long and was stopped.We could not open example.com just now. The site is limiting how often it can be checked. Wait a few minutes, then try again.We could not read enough from example.com to run the check. Make sure the site loads in your browser, then try again.
The object carries exactly these fields.
A domain the key cannot read returns 404 domain_not_found on the list endpoint. A scan id that does not exist, or belongs to a domain the key cannot read, returns 404 not_found.
domains/{domain_id}/scansPath Parameters
domain_idRequiredDomain Id
Query Parameters
cursorCursor
Header Parameters
X-API-KeyX-Api-Key
Successful Response
scans/{scan_id}Successful Response