urlscan-python

The official Python API client for urlscan.io.

Requirements

• Python 3.10+

Installation

pip install urlscan-python

Quickstart

Start by importing urlscan module:

import urlscan

Create a client with your API key:

with urlscan.Client("<your_api_key>") as client:
    ...

[!NOTE] The recommended way to use Client is as a context manager like the above. This will ensure closing a connection when leaving the with block.

Alternatively, you can explicitly close the connection pool without block-usage using ._close():

client = urlscan.Client("<your_api_key>")
try:
    ...
finally:
    client._close()

Scan a URL:

res = client.scan("<url>", visibility="public")
uuid: str = res["uuid"]

Wait for a scan result:

client.wait_for_result(uuid)

Get a scan result:

result = client.get_result(uuid)

Bulk scan:

client.bulk_scan(["<url>", "<url>"], visibility="public")

Alternatively, you can use _and_get_result(s) suffixed methods to do scan, wait and get at once.

client.scan_and_get_result("<url>", visibility="public")
client.bulk_scan_and_get_results(["<url>", "<url>"], visibility="public")

urlscan.Client.search() returns an iterator to iterate search results:

for result in client.search("page.domain:example.com"):
    print(result["_id"])

Pro

Use Pro class to interact with the pro API endpoints:

from urlscan import Pro

with Pro("<your_api_key>") as client:
    res = client.livescan.scan("<url>", scanner_id="us01")
    resource_id: str = res["uuid"]
    result = client.livescan.get_resource(scanner_id="us01", resource_id=resource_id, resource_type="result")

Examples

See Examples.

References

• Client
• Iterator
• Pro
• Errors

Help Wanted?

Please feel free to to open an issue if you find a bug or some feature that you want to see implemented.