# Scans ## Search URL scans `url_scanner.scans.list(ScanListParams**kwargs) -> ScanListResponse` **get** `/accounts/{account_id}/urlscanner/v2/search` Use a subset of ElasticSearch Query syntax to filter scans. Some example queries:

- 'path:"/bundles/jquery.js"': Searches for scans who requested resources with the given path.
- 'page.asn:AS24940 AND hash:xxx': Websites hosted in AS24940 where a resource with the given hash was downloaded.
- 'page.domain:microsoft* AND verdicts.malicious:true AND NOT page.domain:microsoft.com': malicious scans whose hostname starts with "microsoft".
- 'apikey:me AND date:[2025-01 TO 2025-02]': my scans from 2025 January to 2025 February. ### Parameters - `account_id: str` Account ID. - `q: Optional[str]` Filter scans - `size: Optional[int]` Limit the number of objects in the response. ### Returns - `class ScanListResponse: …` - `results: List[Result]` - `_id: str` - `page: ResultPage` - `asn: str` - `country: str` - `ip: str` - `url: str` - `result: str` - `stats: ResultStats` - `data_length: float` - `requests: float` - `uniq_countries: float` - `uniq_ips: float` - `task: ResultTask` - `time: str` - `url: str` - `uuid: str` - `visibility: str` - `verdicts: ResultVerdicts` - `malicious: bool` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) scans = client.url_scanner.scans.list( account_id="account_id", ) print(scans.results) ``` #### Response ```json { "results": [ { "_id": "9626f773-9ffb-4cfb-89d3-30b120fc8011", "page": { "asn": "AS15133", "country": "US", "ip": "93.184.215.14", "url": "https://example.com" }, "result": "https://radar.clouflare.com/scan/9626f773-9ffb-4cfb-89d3-30b120fc8011", "stats": { "dataLength": 2512, "requests": 2, "uniqCountries": 1, "uniqIPs": 1 }, "task": { "time": "2024-09-30T23:54:02.881000+00:00", "url": "https://example.com", "uuid": "9626f773-9ffb-4cfb-89d3-30b120fc8011", "visibility": "public" }, "verdicts": { "malicious": true } } ] } ``` ## Get URL scan `url_scanner.scans.get(strscan_id, ScanGetParams**kwargs) -> ScanGetResponse` **get** `/accounts/{account_id}/urlscanner/v2/result/{scan_id}` Get URL scan by uuid ### Parameters - `account_id: str` Account ID. - `scan_id: str` Scan UUID. ### Returns - `class ScanGetResponse: …` - `data: Data` - `console: List[DataConsole]` - `message: DataConsoleMessage` - `level: str` - `source: str` - `text: str` - `url: str` - `cookies: List[DataCookie]` - `domain: str` - `expires: float` - `http_only: bool` - `name: str` - `path: str` - `priority: str` - `same_party: bool` - `secure: bool` - `session: bool` - `size: float` - `source_port: float` - `source_scheme: str` - `value: str` - `globals: List[DataGlobal]` - `prop: str` - `type: str` - `links: List[DataLink]` - `href: str` - `text: str` - `performance: List[DataPerformance]` - `duration: float` - `entry_type: str` - `name: str` - `start_time: float` - `requests: List[DataRequest]` - `request: DataRequestRequest` - `document_url: str` - `has_user_gesture: bool` - `initiator: DataRequestRequestInitiator` - `host: str` - `type: str` - `url: str` - `redirect_has_extra_info: bool` - `request: DataRequestRequestRequest` - `initial_priority: str` - `is_same_site: bool` - `method: str` - `mixed_content_type: str` - `referrer_policy: str` - `url: str` - `headers: Optional[object]` - `request_id: str` - `type: str` - `wall_time: float` - `frame_id: Optional[str]` - `loader_id: Optional[str]` - `primary_request: Optional[bool]` - `redirect_response: Optional[DataRequestRequestRedirectResponse]` - `charset: str` - `mime_type: str` - `protocol: str` - `remote_ip_address: str` - `remote_port: float` - `security_headers: List[DataRequestRequestRedirectResponseSecurityHeader]` - `name: str` - `value: str` - `security_state: str` - `status: float` - `status_text: str` - `url: str` - `headers: Optional[object]` - `response: DataRequestResponse` - `asn: DataRequestResponseASN` - `asn: str` - `country: str` - `description: str` - `ip: str` - `name: str` - `org: str` - `data_length: float` - `encoded_data_length: float` - `geoip: DataRequestResponseGeoip` - `city: str` - `country: str` - `country_name: str` - `geoname_id: str` - `ll: List[float]` - `region: str` - `has_extra_info: bool` - `request_id: str` - `response: DataRequestResponseResponse` - `charset: str` - `mime_type: str` - `protocol: str` - `remote_ip_address: str` - `remote_port: float` - `security_details: DataRequestResponseResponseSecurityDetails` - `certificate_id: float` - `certificate_transparency_compliance: str` - `cipher: str` - `encrypted_client_hello: bool` - `issuer: str` - `key_exchange: str` - `key_exchange_group: str` - `protocol: str` - `san_list: List[str]` - `server_signature_algorithm: float` - `subject_name: str` - `valid_from: float` - `valid_to: float` - `security_headers: List[DataRequestResponseResponseSecurityHeader]` - `name: str` - `value: str` - `security_state: str` - `status: float` - `status_text: str` - `url: str` - `headers: Optional[object]` - `size: float` - `type: str` - `content_available: Optional[bool]` - `hash: Optional[str]` - `requests: Optional[List[DataRequestRequest]]` - `document_url: str` - `frame_id: str` - `has_user_gesture: bool` - `initiator: DataRequestRequestInitiator` - `type: str` - `loader_id: str` - `redirect_has_extra_info: bool` - `request: DataRequestRequestRequest` - `headers: DataRequestRequestRequestHeaders` - `name: str` - `initial_priority: str` - `is_same_site: bool` - `method: str` - `mixed_content_type: str` - `referrer_policy: str` - `url: str` - `request_id: str` - `type: str` - `wall_time: float` - `lists: Lists` - `asns: List[str]` - `certificates: List[ListsCertificate]` - `issuer: str` - `subject_name: str` - `valid_from: float` - `valid_to: float` - `continents: List[str]` - `countries: List[str]` - `domains: List[str]` - `hashes: List[str]` - `ips: List[str]` - `link_domains: List[str]` - `servers: List[str]` - `urls: List[str]` - `meta: Meta` - `processors: MetaProcessors` - `asn: MetaProcessorsASN` - `data: List[MetaProcessorsASNData]` - `asn: str` - `country: str` - `description: str` - `ip: str` - `name: str` - `dns: MetaProcessorsDNS` - `data: List[MetaProcessorsDNSData]` - `address: str` - `dnssec_valid: bool` - `name: str` - `type: str` - `domain_categories: MetaProcessorsDomainCategories` - `data: List[MetaProcessorsDomainCategoriesData]` - `inherited: object` - `is_primary: bool` - `name: str` - `geoip: MetaProcessorsGeoip` - `data: List[MetaProcessorsGeoipData]` - `geoip: MetaProcessorsGeoipDataGeoip` - `city: str` - `country: str` - `country_name: str` - `ll: List[float]` - `region: str` - `ip: str` - `phishing: MetaProcessorsPhishing` - `data: List[str]` - `radar_rank: MetaProcessorsRadarRank` - `data: List[MetaProcessorsRadarRankData]` - `bucket: str` - `hostname: str` - `rank: Optional[float]` - `wappa: MetaProcessorsWappa` - `data: List[MetaProcessorsWappaData]` - `app: str` - `categories: List[MetaProcessorsWappaDataCategory]` - `name: str` - `priority: float` - `confidence: List[MetaProcessorsWappaDataConfidence]` - `confidence: float` - `name: str` - `pattern: str` - `pattern_type: str` - `confidence_total: float` - `icon: str` - `website: str` - `phishing_v2: Optional[MetaProcessorsPhishingV2]` - `data: List[str]` - `robots_txt: Optional[MetaProcessorsRobotsTXT]` - `data: List[MetaProcessorsRobotsTXTData]` - `rules: MetaProcessorsRobotsTXTDataRules` - `api_empty: MetaProcessorsRobotsTXTDataRulesapi_empty` - `allow: List[str]` - `disallow: List[str]` - `content_signal: Optional[MetaProcessorsRobotsTXTDataRulesapi_emptyContentSignal]` - `ai_input: Optional[str]` - `ai_train: Optional[str]` - `search: Optional[str]` - `crawl_delay: Optional[float]` - `sitemaps: List[str]` - `hash: Optional[str]` - `url_categories: Optional[MetaProcessorsURLCategories]` - `data: List[MetaProcessorsURLCategoriesData]` - `content: List[MetaProcessorsURLCategoriesDataContent]` - `id: float` - `name: str` - `super_category_id: float` - `inherited: MetaProcessorsURLCategoriesDataInherited` - `content: List[MetaProcessorsURLCategoriesDataInheritedContent]` - `id: float` - `name: str` - `super_category_id: float` - `from_: str` - `risks: List[MetaProcessorsURLCategoriesDataInheritedRisk]` - `id: float` - `name: str` - `super_category_id: float` - `name: str` - `risks: List[MetaProcessorsURLCategoriesDataRisk]` - `id: float` - `name: str` - `super_category_id: float` - `page: Page` - `apex_domain: str` - `asn: str` - `asnname: str` - `city: str` - `country: str` - `domain: str` - `ip: str` - `mime_type: str` - `server: str` - `status: str` - `title: str` - `tls_age_days: float` - `tls_issuer: str` - `tls_valid_days: float` - `tls_valid_from: str` - `url: str` - `screenshot: Optional[PageScreenshot]` - `dhash: str` - `mm3_hash: float` - `name: str` - `phash: str` - `scanner: Scanner` - `colo: str` - `country: str` - `stats: Stats` - `domain_stats: List[StatsDomainStat]` - `count: float` - `countries: List[str]` - `domain: str` - `encoded_size: float` - `index: float` - `initiators: List[str]` - `ips: List[str]` - `redirects: float` - `size: float` - `ip_stats: List[StatsIPStat]` - `asn: StatsIPStatASN` - `asn: str` - `country: str` - `description: str` - `ip: str` - `name: str` - `org: str` - `countries: List[str]` - `domains: List[str]` - `encoded_size: float` - `geoip: StatsIPStatGeoip` - `city: str` - `country: str` - `country_name: str` - `ll: List[float]` - `region: str` - `index: float` - `ip: str` - `ipv6: bool` - `redirects: float` - `requests: float` - `size: float` - `count: Optional[float]` - `i_pv6_percentage: float` - `malicious: float` - `protocol_stats: List[StatsProtocolStat]` - `count: float` - `countries: List[str]` - `encoded_size: float` - `ips: List[str]` - `protocol: str` - `size: float` - `resource_stats: List[StatsResourceStat]` - `compression: float` - `count: float` - `countries: List[str]` - `encoded_size: float` - `ips: List[str]` - `percentage: float` - `size: float` - `type: str` - `secure_percentage: float` - `secure_requests: float` - `server_stats: List[StatsServerStat]` - `count: float` - `countries: List[str]` - `encoded_size: float` - `ips: List[str]` - `server: str` - `size: float` - `tls_stats: List[StatsTLSStat]` - `count: float` - `countries: List[str]` - `encoded_size: float` - `ips: List[str]` - `protocols: StatsTLSStatProtocols` - `tls_1_3_aes_128_gcm: float` - `security_state: str` - `size: float` - `total_links: float` - `uniq_asns: float` - `uniq_countries: float` - `task: Task` - `apex_domain: str` - `domain: str` - `dom_url: str` - `method: str` - `options: TaskOptions` - `custom_headers: Optional[object]` Custom headers set. - `screenshots_resolutions: Optional[List[str]]` - `report_url: str` - `screenshot_url: str` - `source: str` - `success: bool` - `time: str` - `url: str` - `uuid: str` - `visibility: str` - `verdicts: Verdicts` - `overall: VerdictsOverall` - `categories: List[str]` - `has_verdicts: bool` - `malicious: bool` - `tags: List[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) scan = client.url_scanner.scans.get( scan_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id="account_id", ) print(scan.data) ``` #### Response ```json { "data": { "console": [ { "message": { "level": "level", "source": "source", "text": "text", "url": "url" } } ], "cookies": [ { "domain": "domain", "expires": 0, "httpOnly": true, "name": "name", "path": "path", "priority": "priority", "sameParty": true, "secure": true, "session": true, "size": 0, "sourcePort": 0, "sourceScheme": "sourceScheme", "value": "value" } ], "globals": [ { "prop": "prop", "type": "type" } ], "links": [ { "href": "href", "text": "text" } ], "performance": [ { "duration": 0, "entryType": "entryType", "name": "name", "startTime": 0 } ], "requests": [ { "request": { "documentURL": "documentURL", "hasUserGesture": true, "initiator": { "host": "host", "type": "type", "url": "url" }, "redirectHasExtraInfo": true, "request": { "initialPriority": "initialPriority", "isSameSite": true, "method": "method", "mixedContentType": "mixedContentType", "referrerPolicy": "referrerPolicy", "url": "url", "headers": {} }, "requestId": "requestId", "type": "type", "wallTime": 0, "frameId": "frameId", "loaderId": "loaderId", "primaryRequest": true, "redirectResponse": { "charset": "charset", "mimeType": "mimeType", "protocol": "protocol", "remoteIPAddress": "remoteIPAddress", "remotePort": 0, "securityHeaders": [ { "name": "name", "value": "value" } ], "securityState": "securityState", "status": 0, "statusText": "statusText", "url": "url", "headers": {} } }, "response": { "asn": { "asn": "asn", "country": "country", "description": "description", "ip": "ip", "name": "name", "org": "org" }, "dataLength": 0, "encodedDataLength": 0, "geoip": { "city": "city", "country": "country", "country_name": "country_name", "geonameId": "geonameId", "ll": [ 0 ], "region": "region" }, "hasExtraInfo": true, "requestId": "requestId", "response": { "charset": "charset", "mimeType": "mimeType", "protocol": "protocol", "remoteIPAddress": "remoteIPAddress", "remotePort": 0, "securityDetails": { "certificateId": 0, "certificateTransparencyCompliance": "certificateTransparencyCompliance", "cipher": "cipher", "encryptedClientHello": true, "issuer": "issuer", "keyExchange": "keyExchange", "keyExchangeGroup": "keyExchangeGroup", "protocol": "protocol", "sanList": [ "string" ], "serverSignatureAlgorithm": 0, "subjectName": "subjectName", "validFrom": 0, "validTo": 0 }, "securityHeaders": [ { "name": "name", "value": "value" } ], "securityState": "securityState", "status": 0, "statusText": "statusText", "url": "url", "headers": {} }, "size": 0, "type": "type", "contentAvailable": true, "hash": "hash" }, "requests": [ { "documentURL": "documentURL", "frameId": "frameId", "hasUserGesture": true, "initiator": { "type": "type" }, "loaderId": "loaderId", "redirectHasExtraInfo": true, "request": { "headers": { "name": "name" }, "initialPriority": "initialPriority", "isSameSite": true, "method": "method", "mixedContentType": "mixedContentType", "referrerPolicy": "referrerPolicy", "url": "url" }, "requestId": "requestId", "type": "type", "wallTime": 0 } ] } ] }, "lists": { "asns": [ "string" ], "certificates": [ { "issuer": "issuer", "subjectName": "subjectName", "validFrom": 0, "validTo": 0 } ], "continents": [ "string" ], "countries": [ "string" ], "domains": [ "string" ], "hashes": [ "string" ], "ips": [ "string" ], "linkDomains": [ "string" ], "servers": [ "string" ], "urls": [ "string" ] }, "meta": { "processors": { "asn": { "data": [ { "asn": "asn", "country": "country", "description": "description", "ip": "ip", "name": "name" } ] }, "dns": { "data": [ { "address": "address", "dnssec_valid": true, "name": "name", "type": "type" } ] }, "domainCategories": { "data": [ { "inherited": {}, "isPrimary": true, "name": "name" } ] }, "geoip": { "data": [ { "geoip": { "city": "city", "country": "country", "country_name": "country_name", "ll": [ 0 ], "region": "region" }, "ip": "ip" } ] }, "phishing": { "data": [ "string" ] }, "radarRank": { "data": [ { "bucket": "bucket", "hostname": "hostname", "rank": 0 } ] }, "wappa": { "data": [ { "app": "app", "categories": [ { "name": "name", "priority": 0 } ], "confidence": [ { "confidence": 0, "name": "name", "pattern": "pattern", "patternType": "patternType" } ], "confidenceTotal": 0, "icon": "icon", "website": "website" } ] }, "phishing_v2": { "data": [ "string" ] }, "robotsTxt": { "data": [ { "rules": { "*": { "allow": [ "string" ], "disallow": [ "string" ], "contentSignal": { "ai-input": "no", "ai-train": "yes", "search": "yes" }, "crawlDelay": 0 } }, "sitemaps": [ "string" ], "hash": "hash" } ] }, "urlCategories": { "data": [ { "content": [ { "id": 0, "name": "name", "super_category_id": 0 } ], "inherited": { "content": [ { "id": 0, "name": "name", "super_category_id": 0 } ], "from": "from", "risks": [ { "id": 0, "name": "name", "super_category_id": 0 } ] }, "name": "name", "risks": [ { "id": 0, "name": "name", "super_category_id": 0 } ] } ] } } }, "page": { "apexDomain": "apexDomain", "asn": "asn", "asnname": "asnname", "city": "city", "country": "country", "domain": "domain", "ip": "ip", "mimeType": "mimeType", "server": "server", "status": "200", "title": "title", "tlsAgeDays": 0, "tlsIssuer": "tlsIssuer", "tlsValidDays": 0, "tlsValidFrom": "tlsValidFrom", "url": "url", "screenshot": { "dhash": "dhash", "mm3Hash": 0, "name": "name", "phash": "phash" } }, "scanner": { "colo": "colo", "country": "country" }, "stats": { "domainStats": [ { "count": 0, "countries": [ "string" ], "domain": "domain", "encodedSize": 0, "index": 0, "initiators": [ "string" ], "ips": [ "string" ], "redirects": 0, "size": 0 } ], "ipStats": [ { "asn": { "asn": "asn", "country": "country", "description": "description", "ip": "ip", "name": "name", "org": "org" }, "countries": [ "string" ], "domains": [ "string" ], "encodedSize": 0, "geoip": { "city": "city", "country": "country", "country_name": "country_name", "ll": [ 0 ], "region": "region" }, "index": 0, "ip": "ip", "ipv6": true, "redirects": 0, "requests": 0, "size": 0, "count": 0 } ], "IPv6Percentage": 0, "malicious": 0, "protocolStats": [ { "count": 0, "countries": [ "string" ], "encodedSize": 0, "ips": [ "string" ], "protocol": "protocol", "size": 0 } ], "resourceStats": [ { "compression": 0, "count": 0, "countries": [ "string" ], "encodedSize": 0, "ips": [ "string" ], "percentage": 0, "size": 0, "type": "type" } ], "securePercentage": 0, "secureRequests": 0, "serverStats": [ { "count": 0, "countries": [ "string" ], "encodedSize": 0, "ips": [ "string" ], "server": "server", "size": 0 } ], "tlsStats": [ { "count": 0, "countries": [ "string" ], "encodedSize": 0, "ips": [ "string" ], "protocols": { "TLS 1.3 / AES_128_GCM": 0 }, "securityState": "securityState", "size": 0 } ], "totalLinks": 0, "uniqASNs": 0, "uniqCountries": 0 }, "task": { "apexDomain": "apexDomain", "domain": "domain", "domURL": "domURL", "method": "method", "options": { "customHeaders": {}, "screenshotsResolutions": [ "string" ] }, "reportURL": "reportURL", "screenshotURL": "screenshotURL", "source": "source", "success": true, "time": "time", "url": "url", "uuid": "uuid", "visibility": "visibility" }, "verdicts": { "overall": { "categories": [ "string" ], "hasVerdicts": true, "malicious": true, "tags": [ "string" ] } } } ``` ## Create URL Scan `url_scanner.scans.create(ScanCreateParams**kwargs) -> ScanCreateResponse` **post** `/accounts/{account_id}/urlscanner/v2/scan` Submit a URL to scan. Check limits at https://developers.cloudflare.com/security-center/investigate/scan-limits/. ### Parameters - `account_id: str` Account ID. - `url: str` - `country: Optional[Literal["AF", "AL", "DZ", 192 more]]` Country to geo egress from - `"AF"` - `"AL"` - `"DZ"` - `"AD"` - `"AO"` - `"AG"` - `"AR"` - `"AM"` - `"AU"` - `"AT"` - `"AZ"` - `"BH"` - `"BD"` - `"BB"` - `"BY"` - `"BE"` - `"BZ"` - `"BJ"` - `"BM"` - `"BT"` - `"BO"` - `"BA"` - `"BW"` - `"BR"` - `"BN"` - `"BG"` - `"BF"` - `"BI"` - `"KH"` - `"CM"` - `"CA"` - `"CV"` - `"KY"` - `"CF"` - `"TD"` - `"CL"` - `"CN"` - `"CO"` - `"KM"` - `"CG"` - `"CR"` - `"CI"` - `"HR"` - `"CU"` - `"CY"` - `"CZ"` - `"CD"` - `"DK"` - `"DJ"` - `"DM"` - `"DO"` - `"EC"` - `"EG"` - `"SV"` - `"GQ"` - `"ER"` - `"EE"` - `"SZ"` - `"ET"` - `"FJ"` - `"FI"` - `"FR"` - `"GA"` - `"GE"` - `"DE"` - `"GH"` - `"GR"` - `"GL"` - `"GD"` - `"GT"` - `"GN"` - `"GW"` - `"GY"` - `"HT"` - `"HN"` - `"HU"` - `"IS"` - `"IN"` - `"ID"` - `"IR"` - `"IQ"` - `"IE"` - `"IL"` - `"IT"` - `"JM"` - `"JP"` - `"JO"` - `"KZ"` - `"KE"` - `"KI"` - `"KW"` - `"KG"` - `"LA"` - `"LV"` - `"LB"` - `"LS"` - `"LR"` - `"LY"` - `"LI"` - `"LT"` - `"LU"` - `"MO"` - `"MG"` - `"MW"` - `"MY"` - `"MV"` - `"ML"` - `"MR"` - `"MU"` - `"MX"` - `"FM"` - `"MD"` - `"MC"` - `"MN"` - `"MS"` - `"MA"` - `"MZ"` - `"MM"` - `"NA"` - `"NR"` - `"NP"` - `"NL"` - `"NZ"` - `"NI"` - `"NE"` - `"NG"` - `"KP"` - `"MK"` - `"NO"` - `"OM"` - `"PK"` - `"PS"` - `"PA"` - `"PG"` - `"PY"` - `"PE"` - `"PH"` - `"PL"` - `"PT"` - `"QA"` - `"RO"` - `"RU"` - `"RW"` - `"SH"` - `"KN"` - `"LC"` - `"VC"` - `"WS"` - `"SM"` - `"ST"` - `"SA"` - `"SN"` - `"RS"` - `"SC"` - `"SL"` - `"SK"` - `"SI"` - `"SB"` - `"SO"` - `"ZA"` - `"KR"` - `"SS"` - `"ES"` - `"LK"` - `"SD"` - `"SR"` - `"SE"` - `"CH"` - `"SY"` - `"TW"` - `"TJ"` - `"TZ"` - `"TH"` - `"BS"` - `"GM"` - `"TL"` - `"TG"` - `"TO"` - `"TT"` - `"TN"` - `"TR"` - `"TM"` - `"UG"` - `"UA"` - `"AE"` - `"GB"` - `"US"` - `"UY"` - `"UZ"` - `"VU"` - `"VE"` - `"VN"` - `"YE"` - `"ZM"` - `"ZW"` - `customagent: Optional[str]` - `custom_headers: Optional[Dict[str, str]]` Set custom headers. - `referer: Optional[str]` - `screenshots_resolutions: Optional[List[Literal["desktop", "mobile", "tablet"]]]` Take multiple screenshots targeting different device types. - `"desktop"` - `"mobile"` - `"tablet"` - `visibility: Optional[Literal["Public", "Unlisted"]]` The option `Public` means it will be included in listings like recent scans and search results. `Unlisted` means it will not be included in the aforementioned listings, users will need to have the scan's ID to access it. A a scan will be automatically marked as unlisted if it fails, if it contains potential PII or other sensitive material. - `"Public"` - `"Unlisted"` ### Returns - `class ScanCreateResponse: …` - `api: str` URL to api report. - `message: str` - `result: str` Public URL to report. - `url: str` Canonical form of submitted URL. Use this if you want to later search by URL. - `uuid: str` Scan ID. - `visibility: Literal["public", "unlisted"]` Submitted visibility status. - `"public"` - `"unlisted"` - `options: Optional[Options]` - `useragent: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) scan = client.url_scanner.scans.create( account_id="account_id", url="https://www.example.com", ) print(scan.uuid) ``` #### Response ```json { "api": "api", "message": "Submission successful", "result": "result", "url": "url", "uuid": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "visibility": "public", "options": { "useragent": "useragent" } } ``` ## Bulk create URL Scans `url_scanner.scans.bulk_create(ScanBulkCreateParams**kwargs) -> ScanBulkCreateResponse` **post** `/accounts/{account_id}/urlscanner/v2/bulk` Submit URLs to scan. Check limits at https://developers.cloudflare.com/security-center/investigate/scan-limits/ and take into account scans submitted in bulk have lower priority and may take longer to finish. ### Parameters - `account_id: str` Account ID. - `body: Optional[Iterable[Body]]` List of urls to scan (up to a 100). - `url: str` - `customagent: Optional[str]` - `custom_headers: Optional[Dict[str, str]]` Set custom headers. - `referer: Optional[str]` - `screenshots_resolutions: Optional[List[Literal["desktop", "mobile", "tablet"]]]` Take multiple screenshots targeting different device types. - `"desktop"` - `"mobile"` - `"tablet"` - `visibility: Optional[Literal["Public", "Unlisted"]]` The option `Public` means it will be included in listings like recent scans and search results. `Unlisted` means it will not be included in the aforementioned listings, users will need to have the scan's ID to access it. A a scan will be automatically marked as unlisted if it fails, if it contains potential PII or other sensitive material. - `"Public"` - `"Unlisted"` ### Returns - `List[ScanBulkCreateResponseItem]` - `api: str` URL to api report. - `result: str` URL to report. - `url: str` Submitted URL - `uuid: str` Scan ID. - `visibility: Literal["public", "unlisted"]` Submitted visibility status. - `"public"` - `"unlisted"` - `options: Optional[ScanBulkCreateResponseItemOptions]` - `useragent: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.url_scanner.scans.bulk_create( account_id="account_id", ) print(response) ``` #### Response ```json [ { "api": "api", "result": "result", "url": "url", "uuid": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "visibility": "public", "options": { "useragent": "useragent" } } ] ``` ## Get URL scan's HAR `url_scanner.scans.har(strscan_id, ScanHARParams**kwargs) -> ScanHARResponse` **get** `/accounts/{account_id}/urlscanner/v2/har/{scan_id}` Get a URL scan's HAR file. See HAR spec at http://www.softwareishard.com/blog/har-12-spec/. ### Parameters - `account_id: str` Account ID. - `scan_id: str` Scan UUID. ### Returns - `class ScanHARResponse: …` - `log: Log` - `creator: LogCreator` - `comment: str` - `name: str` - `version: str` - `entries: List[LogEntry]` - `_initial_priority: str` - `_initiator_type: str` - `_priority: str` - `_request_id: str` - `_request_time: float` - `_resource_type: str` - `cache: object` - `connection: str` - `pageref: str` - `request: LogEntryRequest` - `body_size: float` - `headers: List[LogEntryRequestHeader]` - `name: str` - `value: str` - `headers_size: float` - `http_version: str` - `method: str` - `url: str` - `response: LogEntryResponse` - `_transfer_size: float` - `body_size: float` - `content: LogEntryResponseContent` - `mime_type: str` - `size: float` - `compression: Optional[int]` - `headers: List[LogEntryResponseHeader]` - `name: str` - `value: str` - `headers_size: float` - `http_version: str` - `redirect_url: str` - `status: float` - `status_text: str` - `server_ip_address: str` - `started_date_time: str` - `time: float` - `pages: List[LogPage]` - `id: str` - `page_timings: LogPagePageTimings` - `on_content_load: float` - `on_load: float` - `started_date_time: str` - `title: str` - `version: str` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.url_scanner.scans.har( scan_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id="account_id", ) print(response.log) ``` #### Response ```json { "log": { "creator": { "comment": "https://github.com/sitespeedio/chrome-har", "name": "chrome-har", "version": "0.13.1" }, "entries": [ { "_initialPriority": "VeryHigh", "_initiator_type": "other", "_priority": "VeryHigh", "_requestId": "DDC779F0CB3746BAF283EC1A51B0F2F8", "_requestTime": 114135.331081, "_resourceType": "document", "cache": {}, "connection": "33", "pageref": "page_1", "request": { "bodySize": 0, "headers": [ { "name": "Upgrade-Insecure-Requests", "value": "1" } ], "headersSize": 197, "httpVersion": "http/1.1", "method": "GET", "url": "http://example.com/" }, "response": { "_transferSize": 1071, "bodySize": 648, "content": { "mimeType": "text/html", "size": 1256, "compression": 608 }, "headers": [ { "name": "Content-Encoding", "value": "gzip" } ], "headersSize": 423, "httpVersion": "http/1.1", "redirectURL": "redirectURL", "status": 200, "statusText": "OK" }, "serverIPAddress": "2606:2800:220:1:248:1893:25c8:1946", "startedDateTime": "2023-05-03T17:05:13.196Z", "time": 268.64 } ], "pages": [ { "id": "page_1", "pageTimings": { "onContentLoad": 305.408, "onLoad": 305.169 }, "startedDateTime": "2023-05-03T17:05:13.195Z", "title": "http://example.com/" } ], "version": "1.2" } } ``` ## Get screenshot `url_scanner.scans.screenshot(strscan_id, ScanScreenshotParams**kwargs) -> BinaryResponseContent` **get** `/accounts/{account_id}/urlscanner/v2/screenshots/{scan_id}.png` Get scan's screenshot by resolution (desktop/mobile/tablet). ### Parameters - `account_id: str` Account ID. - `scan_id: str` Scan UUID. - `resolution: Optional[Literal["desktop", "mobile", "tablet"]]` Target device type. - `"desktop"` - `"mobile"` - `"tablet"` ### Returns - `BinaryResponseContent` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.url_scanner.scans.screenshot( scan_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id="account_id", ) print(response) content = response.read() print(content) ``` ## Get URL scan's DOM `url_scanner.scans.dom(strscan_id, ScanDOMParams**kwargs) -> ScanDOMResponse` **get** `/accounts/{account_id}/urlscanner/v2/dom/{scan_id}` Returns a plain text response, with the scan's DOM content as rendered by Chrome. ### Parameters - `account_id: str` Account ID. - `scan_id: str` Scan UUID. ### Returns - `str` HTML of webpage. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.url_scanner.scans.dom( scan_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", account_id="account_id", ) print(response) ``` ## Domain Types ### Scan List Response - `class ScanListResponse: …` - `results: List[Result]` - `_id: str` - `page: ResultPage` - `asn: str` - `country: str` - `ip: str` - `url: str` - `result: str` - `stats: ResultStats` - `data_length: float` - `requests: float` - `uniq_countries: float` - `uniq_ips: float` - `task: ResultTask` - `time: str` - `url: str` - `uuid: str` - `visibility: str` - `verdicts: ResultVerdicts` - `malicious: bool` ### Scan Get Response - `class ScanGetResponse: …` - `data: Data` - `console: List[DataConsole]` - `message: DataConsoleMessage` - `level: str` - `source: str` - `text: str` - `url: str` - `cookies: List[DataCookie]` - `domain: str` - `expires: float` - `http_only: bool` - `name: str` - `path: str` - `priority: str` - `same_party: bool` - `secure: bool` - `session: bool` - `size: float` - `source_port: float` - `source_scheme: str` - `value: str` - `globals: List[DataGlobal]` - `prop: str` - `type: str` - `links: List[DataLink]` - `href: str` - `text: str` - `performance: List[DataPerformance]` - `duration: float` - `entry_type: str` - `name: str` - `start_time: float` - `requests: List[DataRequest]` - `request: DataRequestRequest` - `document_url: str` - `has_user_gesture: bool` - `initiator: DataRequestRequestInitiator` - `host: str` - `type: str` - `url: str` - `redirect_has_extra_info: bool` - `request: DataRequestRequestRequest` - `initial_priority: str` - `is_same_site: bool` - `method: str` - `mixed_content_type: str` - `referrer_policy: str` - `url: str` - `headers: Optional[object]` - `request_id: str` - `type: str` - `wall_time: float` - `frame_id: Optional[str]` - `loader_id: Optional[str]` - `primary_request: Optional[bool]` - `redirect_response: Optional[DataRequestRequestRedirectResponse]` - `charset: str` - `mime_type: str` - `protocol: str` - `remote_ip_address: str` - `remote_port: float` - `security_headers: List[DataRequestRequestRedirectResponseSecurityHeader]` - `name: str` - `value: str` - `security_state: str` - `status: float` - `status_text: str` - `url: str` - `headers: Optional[object]` - `response: DataRequestResponse` - `asn: DataRequestResponseASN` - `asn: str` - `country: str` - `description: str` - `ip: str` - `name: str` - `org: str` - `data_length: float` - `encoded_data_length: float` - `geoip: DataRequestResponseGeoip` - `city: str` - `country: str` - `country_name: str` - `geoname_id: str` - `ll: List[float]` - `region: str` - `has_extra_info: bool` - `request_id: str` - `response: DataRequestResponseResponse` - `charset: str` - `mime_type: str` - `protocol: str` - `remote_ip_address: str` - `remote_port: float` - `security_details: DataRequestResponseResponseSecurityDetails` - `certificate_id: float` - `certificate_transparency_compliance: str` - `cipher: str` - `encrypted_client_hello: bool` - `issuer: str` - `key_exchange: str` - `key_exchange_group: str` - `protocol: str` - `san_list: List[str]` - `server_signature_algorithm: float` - `subject_name: str` - `valid_from: float` - `valid_to: float` - `security_headers: List[DataRequestResponseResponseSecurityHeader]` - `name: str` - `value: str` - `security_state: str` - `status: float` - `status_text: str` - `url: str` - `headers: Optional[object]` - `size: float` - `type: str` - `content_available: Optional[bool]` - `hash: Optional[str]` - `requests: Optional[List[DataRequestRequest]]` - `document_url: str` - `frame_id: str` - `has_user_gesture: bool` - `initiator: DataRequestRequestInitiator` - `type: str` - `loader_id: str` - `redirect_has_extra_info: bool` - `request: DataRequestRequestRequest` - `headers: DataRequestRequestRequestHeaders` - `name: str` - `initial_priority: str` - `is_same_site: bool` - `method: str` - `mixed_content_type: str` - `referrer_policy: str` - `url: str` - `request_id: str` - `type: str` - `wall_time: float` - `lists: Lists` - `asns: List[str]` - `certificates: List[ListsCertificate]` - `issuer: str` - `subject_name: str` - `valid_from: float` - `valid_to: float` - `continents: List[str]` - `countries: List[str]` - `domains: List[str]` - `hashes: List[str]` - `ips: List[str]` - `link_domains: List[str]` - `servers: List[str]` - `urls: List[str]` - `meta: Meta` - `processors: MetaProcessors` - `asn: MetaProcessorsASN` - `data: List[MetaProcessorsASNData]` - `asn: str` - `country: str` - `description: str` - `ip: str` - `name: str` - `dns: MetaProcessorsDNS` - `data: List[MetaProcessorsDNSData]` - `address: str` - `dnssec_valid: bool` - `name: str` - `type: str` - `domain_categories: MetaProcessorsDomainCategories` - `data: List[MetaProcessorsDomainCategoriesData]` - `inherited: object` - `is_primary: bool` - `name: str` - `geoip: MetaProcessorsGeoip` - `data: List[MetaProcessorsGeoipData]` - `geoip: MetaProcessorsGeoipDataGeoip` - `city: str` - `country: str` - `country_name: str` - `ll: List[float]` - `region: str` - `ip: str` - `phishing: MetaProcessorsPhishing` - `data: List[str]` - `radar_rank: MetaProcessorsRadarRank` - `data: List[MetaProcessorsRadarRankData]` - `bucket: str` - `hostname: str` - `rank: Optional[float]` - `wappa: MetaProcessorsWappa` - `data: List[MetaProcessorsWappaData]` - `app: str` - `categories: List[MetaProcessorsWappaDataCategory]` - `name: str` - `priority: float` - `confidence: List[MetaProcessorsWappaDataConfidence]` - `confidence: float` - `name: str` - `pattern: str` - `pattern_type: str` - `confidence_total: float` - `icon: str` - `website: str` - `phishing_v2: Optional[MetaProcessorsPhishingV2]` - `data: List[str]` - `robots_txt: Optional[MetaProcessorsRobotsTXT]` - `data: List[MetaProcessorsRobotsTXTData]` - `rules: MetaProcessorsRobotsTXTDataRules` - `api_empty: MetaProcessorsRobotsTXTDataRulesapi_empty` - `allow: List[str]` - `disallow: List[str]` - `content_signal: Optional[MetaProcessorsRobotsTXTDataRulesapi_emptyContentSignal]` - `ai_input: Optional[str]` - `ai_train: Optional[str]` - `search: Optional[str]` - `crawl_delay: Optional[float]` - `sitemaps: List[str]` - `hash: Optional[str]` - `url_categories: Optional[MetaProcessorsURLCategories]` - `data: List[MetaProcessorsURLCategoriesData]` - `content: List[MetaProcessorsURLCategoriesDataContent]` - `id: float` - `name: str` - `super_category_id: float` - `inherited: MetaProcessorsURLCategoriesDataInherited` - `content: List[MetaProcessorsURLCategoriesDataInheritedContent]` - `id: float` - `name: str` - `super_category_id: float` - `from_: str` - `risks: List[MetaProcessorsURLCategoriesDataInheritedRisk]` - `id: float` - `name: str` - `super_category_id: float` - `name: str` - `risks: List[MetaProcessorsURLCategoriesDataRisk]` - `id: float` - `name: str` - `super_category_id: float` - `page: Page` - `apex_domain: str` - `asn: str` - `asnname: str` - `city: str` - `country: str` - `domain: str` - `ip: str` - `mime_type: str` - `server: str` - `status: str` - `title: str` - `tls_age_days: float` - `tls_issuer: str` - `tls_valid_days: float` - `tls_valid_from: str` - `url: str` - `screenshot: Optional[PageScreenshot]` - `dhash: str` - `mm3_hash: float` - `name: str` - `phash: str` - `scanner: Scanner` - `colo: str` - `country: str` - `stats: Stats` - `domain_stats: List[StatsDomainStat]` - `count: float` - `countries: List[str]` - `domain: str` - `encoded_size: float` - `index: float` - `initiators: List[str]` - `ips: List[str]` - `redirects: float` - `size: float` - `ip_stats: List[StatsIPStat]` - `asn: StatsIPStatASN` - `asn: str` - `country: str` - `description: str` - `ip: str` - `name: str` - `org: str` - `countries: List[str]` - `domains: List[str]` - `encoded_size: float` - `geoip: StatsIPStatGeoip` - `city: str` - `country: str` - `country_name: str` - `ll: List[float]` - `region: str` - `index: float` - `ip: str` - `ipv6: bool` - `redirects: float` - `requests: float` - `size: float` - `count: Optional[float]` - `i_pv6_percentage: float` - `malicious: float` - `protocol_stats: List[StatsProtocolStat]` - `count: float` - `countries: List[str]` - `encoded_size: float` - `ips: List[str]` - `protocol: str` - `size: float` - `resource_stats: List[StatsResourceStat]` - `compression: float` - `count: float` - `countries: List[str]` - `encoded_size: float` - `ips: List[str]` - `percentage: float` - `size: float` - `type: str` - `secure_percentage: float` - `secure_requests: float` - `server_stats: List[StatsServerStat]` - `count: float` - `countries: List[str]` - `encoded_size: float` - `ips: List[str]` - `server: str` - `size: float` - `tls_stats: List[StatsTLSStat]` - `count: float` - `countries: List[str]` - `encoded_size: float` - `ips: List[str]` - `protocols: StatsTLSStatProtocols` - `tls_1_3_aes_128_gcm: float` - `security_state: str` - `size: float` - `total_links: float` - `uniq_asns: float` - `uniq_countries: float` - `task: Task` - `apex_domain: str` - `domain: str` - `dom_url: str` - `method: str` - `options: TaskOptions` - `custom_headers: Optional[object]` Custom headers set. - `screenshots_resolutions: Optional[List[str]]` - `report_url: str` - `screenshot_url: str` - `source: str` - `success: bool` - `time: str` - `url: str` - `uuid: str` - `visibility: str` - `verdicts: Verdicts` - `overall: VerdictsOverall` - `categories: List[str]` - `has_verdicts: bool` - `malicious: bool` - `tags: List[str]` ### Scan Create Response - `class ScanCreateResponse: …` - `api: str` URL to api report. - `message: str` - `result: str` Public URL to report. - `url: str` Canonical form of submitted URL. Use this if you want to later search by URL. - `uuid: str` Scan ID. - `visibility: Literal["public", "unlisted"]` Submitted visibility status. - `"public"` - `"unlisted"` - `options: Optional[Options]` - `useragent: Optional[str]` ### Scan Bulk Create Response - `List[ScanBulkCreateResponseItem]` - `api: str` URL to api report. - `result: str` URL to report. - `url: str` Submitted URL - `uuid: str` Scan ID. - `visibility: Literal["public", "unlisted"]` Submitted visibility status. - `"public"` - `"unlisted"` - `options: Optional[ScanBulkCreateResponseItemOptions]` - `useragent: Optional[str]` ### Scan HAR Response - `class ScanHARResponse: …` - `log: Log` - `creator: LogCreator` - `comment: str` - `name: str` - `version: str` - `entries: List[LogEntry]` - `_initial_priority: str` - `_initiator_type: str` - `_priority: str` - `_request_id: str` - `_request_time: float` - `_resource_type: str` - `cache: object` - `connection: str` - `pageref: str` - `request: LogEntryRequest` - `body_size: float` - `headers: List[LogEntryRequestHeader]` - `name: str` - `value: str` - `headers_size: float` - `http_version: str` - `method: str` - `url: str` - `response: LogEntryResponse` - `_transfer_size: float` - `body_size: float` - `content: LogEntryResponseContent` - `mime_type: str` - `size: float` - `compression: Optional[int]` - `headers: List[LogEntryResponseHeader]` - `name: str` - `value: str` - `headers_size: float` - `http_version: str` - `redirect_url: str` - `status: float` - `status_text: str` - `server_ip_address: str` - `started_date_time: str` - `time: float` - `pages: List[LogPage]` - `id: str` - `page_timings: LogPagePageTimings` - `on_content_load: float` - `on_load: float` - `started_date_time: str` - `title: str` - `version: str` ### Scan DOM Response - `str` HTML of webpage.