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
| Name | Type | Required | Values and limits |
|---|---|---|---|
scan_id | string | Yes | |
wait_seconds | integer | No | 0 to 25 |
What it answers
Every answer has status and, where useful, message in plain words.
| Field | Meaning |
|---|---|
status | running, queued, complete, failed or cancelled. |
scan_status | The scan's own state, as the report page shows it. |
steps, engines | While running: each step and its state, and per AI how many questions have an answer (answered of of). |
report_markdown | When complete: the mini report as text, ready to read or quote. |
phrases | The questions asked. |
mode | How the answers were obtained, in words. |
report_url | The full report page (sign-in required). |
four_way | When 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
| status | What it means |
|---|---|
not_found | No scan with that id on this account. |
failed | No AI returned an answer, so there's nothing honest to show. The free scan wasn't used. |
cancelled | The scan was stopped. |
forbidden | The 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 error | An 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.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_scan",
"arguments": {
"scan_id": "00000000-0000-4000-8000-000000000001",
"wait_seconds": 20
}
}
}{
"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."
}