https://github.com/urlscan/urlscan-python
The official Python API client for urlscan.io
https://github.com/urlscan/urlscan-python
Last synced: 4 months ago
JSON representation
The official Python API client for urlscan.io
- Host: GitHub
- URL: https://github.com/urlscan/urlscan-python
- Owner: urlscan
- License: mit
- Created: 2025-03-24T08:17:00.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-04T08:37:21.000Z (8 months ago)
- Last Synced: 2025-11-04T10:19:17.870Z (8 months ago)
- Language: Python
- Homepage: https://urlscan.github.io/urlscan-python/
- Size: 806 KB
- Stars: 14
- Watchers: 5
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# urlscan-python
[](https://badge.fury.io/py/urlscan-python)
The official Python API client for urlscan.io.
## Requirements
- Python 3.10+
## Installation
```bash
pip install urlscan-python
```
## Quickstart
Start by importing `urlscan` module:
```py
import urlscan
```
Create a client with your API key:
```py
with urlscan.Client("") 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()`:
>
> ```py
> client = urlscan.Client("")
> try:
> ...
> finally:
> client._close()
> ```
Scan a URL:
```py
res = client.scan("", visibility="public")
uuid: str = res["uuid"]
```
Wait for a scan result:
```py
client.wait_for_result(uuid)
```
Get a scan result:
```py
result = client.get_result(uuid)
```
Bulk scan:
```py
client.bulk_scan(["", ""], visibility="public")
```
Alternatively, you can use `_and_get_result(s)` suffixed methods to do scan, wait and get at once.
```py
client.scan_and_get_result("", visibility="public")
client.bulk_scan_and_get_results(["", ""], visibility="public")
```
`urlscan.Client.search()` returns an iterator to iterate search results:
```py
for result in client.search("page.domain:example.com"):
print(result["_id"])
```
### Pro
Use `Pro` class to interact with the pro API endpoints:
```py
from urlscan import Pro
with Pro("") as client:
res = client.livescan.scan("", 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](https://github.com/urlscan/urlscan-python/tree/main/examples/).
## References
- [Client](https://urlscan.github.io/urlscan-python/references/client/)
- [Iterator](https://urlscan.github.io/urlscan-python/references/iterator/)
- [Pro](https://urlscan.github.io/urlscan-python/references/pro/)
- [Errors](https://urlscan.github.io/urlscan-python/references/errors/)
## Help Wanted?
Please feel free to to [open an issue](https://github.com/urlscan/urlscan-python/issues/new) if you find a bug or some feature that you want to see implemented.