Skip to content
API Endpoints/
/
Response

urlscan.io APIs (1.0.0)

Introduction

API endpoints for urlscan.io and urlscan Pro. Most of these API endpoints require authentication.

The fastest way to start working with our APIs is by using one of the many existing commercial or open-source integrations.

Download OpenAPI description
urlscan-openapi.json
urlscan-openapi.yaml
Overview
urlscan Support
support@urlscan.io
Languages
Servers
https://urlscan.io

Generic

API endpoints related to the platform or the user account.

Operations

Scanning

These APIs allow URLs to be scanned and the results of the scans to be retrieved.

Operations

Scan

Request

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

Security
apikeyAuth
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"]
overrideSafetyboolean

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

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
application/json
{
  "uuid": "68e26c59-2eae-437b-aeb1-cf750fafe7d7",
  "visibility": "public",
  "url": "https://urlscan.io/",
  "country": "de"
}

Result

Request

Using the Scan ID received from the Submission API, you can use the Result API to poll for the scan. The most efficient approach would be to wait at least 10 seconds before starting to poll, and then only polling 2-second intervals with an eventual upper timeout in case the scan does not return.

Security
apikeyAuth
Path
scanIdstring(uuid)required

UUID of scan result

curl -i -X GET \
  'https://urlscan.io/api/v1/result/{scanId}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
dataobject

Raw scan data including network requests, responses, cookies, console logs, and page elements

statsobject

Statistical analysis of the scan including resource counts, protocols, security metrics, and geographic distribution

metaobject

Enriched metadata from external processors including domain rankings, geolocation, DNS records, and ASN information

taskobject

Information about the scan task including configuration, URLs, and submission details

pageobject

Information about the scanned page including server details, location, and network properties

listsobject

Aggregated lists of unique elements found during the scan including IPs, domains, URLs, and certificates

verdictsobject

Security verdicts and threat analysis from multiple sources including urlscan.io, third-party engines, and community ratings

submitterobject

Information about the entity that submitted the scan request

Response
application/json
{
  "data": {
    "requests": [ … ],
    "cookies": [ … ],
    "console": [ … ],
    "links": [ … ],
    "timing": { … },
    "globals": [ … ]
  },
  "stats": {
    "resourceStats": [ … ],
    "protocolStats": [ … ],
    "tlsStats": [ … ],
    "serverStats": [ … ],
    "domainStats": [ … ],
    "regDomainStats": [ … ],
    "secureRequests": 55,
    "securePercentage": 100,
    "IPv6Percentage": 80,
    "uniqCountries": 1,
    "totalLinks": 10,
    "malicious": 0,
    "adBlocked": 0,
    "ipStats": [ … ]
  },
  "meta": {
    "processors": { … }
  },
  "task": {
    "uuid": "68e26c59-2eae-437b-aeb1-cf750fafe7d7",
    "time": "2023-08-18T10:27:47.342Z",
    "url": "https://urlscan.io/",
    "visibility": "public",
    "method": "api",
    "source": "d1675d21",
    "tags": [],
    "reportURL": "https://urlscan.io/result/68e26c59-2eae-437b-aeb1-cf750fafe7d7/",
    "screenshotURL": "https://urlscan.io/screenshots/68e26c59-2eae-437b-aeb1-cf750fafe7d7.png",
    "domURL": "https://urlscan.io/dom/68e26c59-2eae-437b-aeb1-cf750fafe7d7/"
  },
  "page": {
    "url": "https://urlscan.io/",
    "domain": "urlscan.io",
    "country": "DE",
    "city": "",
    "server": "nginx",
    "ip": "49.12.22.106",
    "asn": "AS24940",
    "asnname": "HETZNER-AS, DE"
  },
  "lists": {
    "ips": [ … ],
    "countries": [ … ],
    "asns": [ … ],
    "domains": [ … ],
    "servers": [ … ],
    "urls": [ … ],
    "linkDomains": [ … ],
    "certificates": [ … ],
    "hashes": [ … ]
  },
  "verdicts": {
    "overall": { … },
    "urlscan": { … },
    "engines": { … },
    "community": { … }
  },
  "submitter": {
    "country": "US"
  }
}

Screenshot

Request

Use the scan UUID to retrieve the screenshot for a scan once the scan has finished.

Security
apikeyAuth
Path
scanIdstring(uuid)required

UUID of scan result

curl -i -X GET \
  'https://urlscan.io/screenshots/{scanId}.png' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyimage/png
string(binary)

DOM

Request

Use the scan UUID to retrieve the DOM snapshot for a scan once the scan has finished.

Security
apikeyAuth
Path
scanIdstring(uuid)required

UUID of scan result

curl -i -X GET \
  'https://urlscan.io/dom/{scanId}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

DOM snapshot of the page

Bodytext/plain
string

Response

Request

Get a (Script|Document|Fetch|XHR) response in plain text format by SHA256 hash. Note that this endpoint returns the content as text/plain. If you need to download a binary file (like a ZIP file, etc.), use the Download a file endpoint instead.

Security
apikeyAuth
Path
fileHashstringrequired

SHA256 hash of response

curl -i -X GET \
  'https://urlscan.io/responses/{fileHash}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Response content in plain text format

Bodytext/plain
string

Available Countries

Request

Retrieve countries available for scanning using the Scan API

Security
apikeyAuth
curl -i -X GET \
  https://urlscan.io/api/v1/availableCountries \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
countriesArray of arrays

List of available countries

Response
application/json
{
  "countries": [
    "de",
    "us",
    "jp",
    "fr",
    "gb",
    "nl",
    "ca",
    "it",
    "es",
    "se",
    "fi",
    "dk",
    "no",
    "is",
    "au",
    "nz",
    "pl",
    "sg",
    "ge",
    "pt",
    "at",
    "ch"
  ]
}

Available User Agents

Request

Get grouped user agents to use with the Scan API.

Security
apikeyAuth
curl -i -X GET \
  https://urlscan.io/api/v1/userAgents \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
userAgentsArray of objectsrequired
userAgents[].​groupstringrequired

Browser or device group name

userAgents[].​useragentsArray of stringsrequired

Array of user agent strings for this group

Response
application/json
{
  "userAgents": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}

Live Scanning

urlscan Pro - Live Scanning allows users to scan websites from different geographical locations and using different device settings.

See additional info about this proprietary feature on urlscan Pro.

Operations

Saved Searches

urlscan Pro - Saved Searches are rules that are executed inline against new incoming scans and hostnames.

Operations

Subscriptions

urlscan Pro - Subscriptions allow notifications for Saved Searches.

Operations

Hostnames

urlscan Pro - Historical information on hostnames and domains

Operations

Brands

urlscan Pro - Information about tracked brands

Operations

Files

urlscan Pro - Downloaded files

Operations

Incidents

urlscan Pro - Incidents track observables, like hostnames and domains, and automatically scan and alert on changes.

Operations

Channels

Operations

Data Dumps

Operations