Skip to content

get_scan

Get a scan.

Current state of a scan, or the finished mini report as text. wait_seconds (0 to 25) waits for completion before answering; call again if it is still running.

Who can use it

Access
Any account, for its own scans.
Scope
scan:read
Changes anything
No. Read-only.

Inputs

NameTypeRequiredValues and limits
scan_idstringYes
wait_secondsintegerNo0 to 25

What it answers

Every answer has status and, where useful, message in plain words.

FieldMeaning
statusrunning, queued, complete, failed or cancelled.
scan_statusThe scan's own state, as the report page shows it.
steps, enginesWhile running: each step and its state, and per AI how many questions have an answer (answered of of).
report_markdownWhen complete: the mini report as text, ready to read or quote.
phrasesThe questions asked.
modeHow the answers were obtained, in words.
report_urlThe full report page (sign-in required).
four_wayWhen complete: each live-search answer in one of four boxes (named_cited, named_not_cited, cited_not_named, neither), with answers as the total, no_links (answers with no links at all, inside named_not_cited or neither) and the same per AI in by_ai; training_data apart as named of answers (no links, so never cited); labels gives the four in words. Counts, never added across the two kinds of answer.

Errors

statusWhat it means
not_foundNo scan with that id on this account.
failedNo AI returned an answer, so there's nothing honest to show. The free scan wasn't used.
cancelledThe scan was stopped.
forbiddenThe credential lacks the tool's scope, or an agent's owner has no ScanFree account yet (the owner signs in on the website once).
Input validation errorAn argument doesn't match the schema below. The call fails with MCP error -32602, naming the field.

Errors before the tool runs (a missing key, too many requests) are on the MCP page.

Example

Example shape; values are illustrative.

The call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_scan",
    "arguments": {
      "scan_id": "00000000-0000-4000-8000-000000000001",
      "wait_seconds": 20
    }
  }
}
The answer (structured content)
{
  "status": "running",
  "scan_id": "00000000-0000-4000-8000-000000000001",
  "report_url": "https://app.scanfree.dev/scan/00000000-0000-4000-8000-000000000001",
  "scan_status": "running",
  "steps": {
    "site": "done",
    "audit": "running"
  },
  "engines": [
    {
      "engine": "ChatGPT",
      "answered": 3,
      "of": 6
    },
    {
      "engine": "Perplexity",
      "answered": 6,
      "of": 6
    }
  ],
  "message": "Call again with wait_seconds to keep waiting."
}