The official Python API client for urlscan.io.
- Python 3.10+
pip install urlscan-pythonStart by importing urlscan module:
import urlscanCreate 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"])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")See Examples.
Please feel free to to open an issue if you find a bug or some feature that you want to see implemented.