list_scans
List recent scans.
The account's recent scans with status, date and report link.
Who can use it
- Access
- Any account.
- Scope
scan:read- Changes anything
- No. Read-only.
Inputs
| Name | Type | Required | Values and limits |
|---|---|---|---|
limit | integer | No | 1 to 50 |
What it answers
Every answer has status and, where useful, message in plain words.
| Field | Meaning |
|---|---|
scans | Newest first: scan_id, status, mode, date (YYYY-MM-DD), site and report_url. |
Errors
| status | What it means |
|---|---|
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": "list_scans",
"arguments": {
"limit": 2
}
}
}{
"status": "ok",
"scans": [
{
"scan_id": "00000000-0000-4000-8000-000000000001",
"status": "complete",
"mode": "live_search",
"date": "2026-11-20",
"site": "example.com",
"report_url": "https://app.scanfree.dev/scan/00000000-0000-4000-8000-000000000001"
}
]
}