API Endpoints
/
Search

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

Languages
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

Search

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

Operations

Search

Request

The Search API is used to find historical scans performed on the platform. Some data sources and searchable fields are only available on urlscan Pro.

The API search will only indicate an exact count of results up to 10,000 results in the total property. After that the has_more flag will be true. Use the sort value of the last (i.e. oldest) scan result in the current list of results as a parameter for the next Search API call. Supply this value in the search_after query parameter for getting the next (older) batch of results.

API search will find Public scans performed by anyone as well as Unlisted and Private scans performed by you or your teams. For query syntax and searchable fields, refer to https://urlscan.io/docs/search/

Security
apikeyAuth
Query
qstring

Search Query (Elasticsearch Query String)

Example: q=page.domain:example.com
sizeinteger<= 10000

Number of results to return

Example: size=100
search_afterstring

For retrieving the next batch of results, send the value of the sort attribute of the last (oldest) result you received (comma-separated) from the previous call.

datasourcestring

Datasources to search: scans (urlscan.io), hostnames, incidents, notifications, certificates (urlscan Pro)

Enum"scans""hostnames""incidents""notifications""certificates"
Example: datasource=scans
curl -i -X GET \
  'http://urlscan.io/api/v1/search?datasource=scans&q=page.domain%3Aexample.com&search_after=string&size=100' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
resultsArray of arrays

Array of search results

totalinteger

Total number of results with an exact count up to 10,000 results.

tookinteger

Search request time in milliseconds.

has_moreboolean

True if there are more than 10,000 results.

Response
application/json
{
  "results": [
    { … },
    { … }
  ],
  "total": 10000,
  "took": 23,
  "has_more": true
}

Structure Search

Request

urlscan Pro - Get structurally similar results to a specific scan. See description for this propietary feature on urlscan Pro.

Security
apikeyAuth
Path
scanIdstringrequired

The original scan to compare to

Example: 68e26c59-2eae-437b-aeb1-cf750fafe7d7
Query
qstring

Additional query filter

Example: q=page.domain:urlscan.io
sizeinteger

Maximum results per call

Example: size=10
search_afterstring

Parameter to iterate over older results

curl -i -X GET \
  'http://urlscan.io/api/v1/pro/result/68e26c59-2eae-437b-aeb1-cf750fafe7d7/similar/?q=page.domain%3Aurlscan.io&search_after=string&size=10' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
resultsArray of arrays

Array of search results

totalinteger

Total number of results with an exact count up to 10,000 results.

tookinteger

Search request time in milliseconds.

has_moreboolean

True if there are more than 10,000 results.

Response
application/json
{
  "results": [
    { … },
    { … }
  ],
  "total": 7684,
  "took": 72,
  "has_more": false
}

PhishfeedDeprecated

Request

urlscan Pro - The Phishing URL endpoint is a convenience method over the Search API for retrieving detected pages. Unless you have a specific reason not to, you should use the Search API instead!

Security
apikeyAuth
Query
qstring
Example: q=date:>now-24h
limitinteger

How many results to return

Example: limit=10
formatstring

Can be one of csv, tsv, or json

Enum"csv""tsv""json"
Example: format=json
curl -i -X GET \
  'http://urlscan.io/api/v1/pro/phishfeed?format=json&limit=10&q=date%3A%3Enow-24h' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
resultsArray of arrays

Array of search results

totalinteger

Total number of results with an exact count up to 10,000 results.

tookinteger

Search request time in milliseconds.

has_moreboolean

True if there are more than 10,000 results.

Response
application/json
{
  "results": [
    { … },
    { … }
  ],
  "total": 10000,
  "took": 23,
  "has_more": true
}

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