Skip to content
/Scanning

Scan

Request

Submit a URL to be scanned and control options for how the scan should be performed.

Security
apikeyAuth(Required scopes: readwrite)
Bodyapplication/jsonrequired
urlstring, (uri)required

The URL to be scanned

Example:"https://urlscan.io"
visibilitystring

Intended visibility of the final scan result

Default:"public"
Enum:"public""unlisted""private"
Example:"public"
countrystring

Country to scan from. ISO 3166-1 alpha-2 format. If not supplied, an appropriate country will automatically be chosen.

Example:"de"
tagsArray of strings, <= 10 items

User-defined tags to annotate this scan, e.g. "phishing" or "malicious".

Example:
[
  "iloveurlscan",
  "testing"
]
overrideSafetystring

If set to any value, this will disable reclassification of URLs with potential PII in them. Use with care!

refererstring

Override HTTP referer for this scan

customagentstring

Override HTTP User-Agent for this scan

POST
/api/v1/scan
curl -i -X POST \
  https://urlscan.io/api/v1/scan \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "url": "https://urlscan.io",
    "visibility": "public",
    "country": "de",
    "tags": [
      "iloveurlscan",
      "testing"
    ]
  }'

Responses

OK

Bodyapplication/json
uuidstring, (uuid)

UUID for scan result, also called $scanId

countrystring

Country for scanning

visibilitystring

Determined visibility for scan

urlstring, (uri)

Determined URL being scanned

Response
{
  "uuid": "68e26c59-2eae-437b-aeb1-cf750fafe7d7",
  "visibility": "public",
  "url": "https://urlscan.io/",
  "country": "de"
}