{"id":34100022,"url":"https://github.com/urlscan/urlscan-python","last_synced_at":"2026-02-25T02:13:22.985Z","repository":{"id":292818467,"uuid":"953877492","full_name":"urlscan/urlscan-python","owner":"urlscan","description":"The official Python API client for urlscan.io","archived":false,"fork":false,"pushed_at":"2025-11-04T08:37:21.000Z","size":825,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-11-04T10:19:17.870Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://urlscan.github.io/urlscan-python/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urlscan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-24T08:17:00.000Z","updated_at":"2025-11-04T08:37:18.000Z","dependencies_parsed_at":"2025-05-12T10:50:17.588Z","dependency_job_id":null,"html_url":"https://github.com/urlscan/urlscan-python","commit_stats":null,"previous_names":["urlscan/urlscan-python"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/urlscan/urlscan-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlscan%2Furlscan-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlscan%2Furlscan-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlscan%2Furlscan-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlscan%2Furlscan-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urlscan","download_url":"https://codeload.github.com/urlscan/urlscan-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urlscan%2Furlscan-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27731318,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-14T02:00:11.348Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-14T16:33:22.782Z","updated_at":"2026-02-25T02:13:22.970Z","avatar_url":"https://github.com/urlscan.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# urlscan-python\n\n[![PyPI version](https://badge.fury.io/py/urlscan-python.svg)](https://badge.fury.io/py/urlscan-python)\n\nThe official Python API client for urlscan.io.\n\n## Requirements\n\n- Python 3.10+\n\n## Installation\n\n```bash\npip install urlscan-python\n```\n\n## Quickstart\n\nStart by importing `urlscan` module:\n\n```py\nimport urlscan\n```\n\nCreate a client with your API key:\n\n```py\nwith urlscan.Client(\"\u003cyour_api_key\u003e\") as client:\n    ...\n```\n\n\u003e [!NOTE]\n\u003e 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.\n\u003e\n\u003e Alternatively, you can explicitly close the connection pool without block-usage using `._close()`:\n\u003e\n\u003e ```py\n\u003e client = urlscan.Client(\"\u003cyour_api_key\u003e\")\n\u003e try:\n\u003e     ...\n\u003e finally:\n\u003e     client._close()\n\u003e ```\n\nScan a URL:\n\n```py\nres = client.scan(\"\u003curl\u003e\", visibility=\"public\")\nuuid: str = res[\"uuid\"]\n```\n\nWait for a scan result:\n\n```py\nclient.wait_for_result(uuid)\n```\n\nGet a scan result:\n\n```py\nresult = client.get_result(uuid)\n```\n\nBulk scan:\n\n```py\nclient.bulk_scan([\"\u003curl\u003e\", \"\u003curl\u003e\"], visibility=\"public\")\n```\n\nAlternatively, you can use `_and_get_result(s)` suffixed methods to do scan, wait and get at once.\n\n```py\nclient.scan_and_get_result(\"\u003curl\u003e\", visibility=\"public\")\nclient.bulk_scan_and_get_results([\"\u003curl\u003e\", \"\u003curl\u003e\"], visibility=\"public\")\n```\n\n`urlscan.Client.search()` returns an iterator to iterate search results:\n\n```py\nfor result in client.search(\"page.domain:example.com\"):\n    print(result[\"_id\"])\n```\n\n### Pro\n\nUse `Pro` class to interact with the pro API endpoints:\n\n```py\nfrom urlscan import Pro\n\nwith Pro(\"\u003cyour_api_key\u003e\") as client:\n    res = client.livescan.scan(\"\u003curl\u003e\", scanner_id=\"us01\")\n    resource_id: str = res[\"uuid\"]\n    result = client.livescan.get_resource(scanner_id=\"us01\", resource_id=resource_id, resource_type=\"result\")\n```\n\n## Examples\n\nSee [Examples](https://github.com/urlscan/urlscan-python/tree/main/examples/).\n\n## References\n\n- [Client](https://urlscan.github.io/urlscan-python/references/client/)\n- [Iterator](https://urlscan.github.io/urlscan-python/references/iterator/)\n- [Pro](https://urlscan.github.io/urlscan-python/references/pro/)\n- [Errors](https://urlscan.github.io/urlscan-python/references/errors/)\n\n## Help Wanted?\n\nPlease 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furlscan%2Furlscan-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furlscan%2Furlscan-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furlscan%2Furlscan-python/lists"}