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.

External Resources

Download OpenAPI description

urlscan-openapi.json

urlscan-openapi.yaml

Overview

urlscan Support

support@urlscan.io

Servers

http://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: ["postman","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 \
  http://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": [
      "postman",
      "testing"
    ]
  }'

Responses

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 \
  'http://urlscan.io/api/v1/result/{scanId}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

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 \
  'http://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 \
  'http://urlscan.io/dom/{scanId}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

DOM snapshot of the page

Bodytext/plain

string

Available Countries

Request

Retrieve countries available for scanning using the Scan API

Security

apikeyAuth

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

Responses

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 \
  http://urlscan.io/api/v1/userAgents \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

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": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}

Search

The Search API allows users to search for historically website scans, hostnames, domains, TLS certificates and incidents.

Operations

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

urlscan.io APIs (1.0.0)

Introduction

External Resources

Generic

Scanning

Scan

Request

Responses

Was this helpful?

Result

Request

Responses

Was this helpful?

Screenshot

Request

Responses

Was this helpful?

DOM

Request

Responses

Was this helpful?

Available Countries

Request

Responses

Was this helpful?

Available User Agents

Request

Responses

Was this helpful?

Search

Live Scanning

Saved Searches

Subscriptions

Hostnames

Brands

Files

Incidents