Skip to content

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

NameTypeRequiredValues and limits
limitintegerNo1 to 50

What it answers

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

FieldMeaning
scansNewest first: scan_id, status, mode, date (YYYY-MM-DD), site and report_url.

Errors

statusWhat it means
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": "list_scans",
    "arguments": {
      "limit": 2
    }
  }
}
The answer (structured content)
{
  "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"
    }
  ]
}