Skip to content
Cloudflare API
Start here
API Reference
URL Scanner
Scans

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/.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
URL Scanner WriteURL Scanner Read
ParametersExpand Collapse
account_id: str

Account ID.

url: str
country: Optional[Literal["AF", "AL", "DZ", 192 more]]

Country to geo egress from

One of the following:
"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]
maxLength4096
custom_headers: Optional[Dict[str, str]]

Set custom headers.

referer: Optional[str]
maxLength4096
screenshots_resolutions: Optional[List[Literal["desktop", "mobile", "tablet"]]]

Take multiple screenshots targeting different device types.

One of the following:
"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.

One of the following:
"Public"
"Unlisted"
ReturnsExpand Collapse
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.

formatuuid
visibility: Literal["public", "unlisted"]

Submitted visibility status.

One of the following:
"public"
"unlisted"
options: Optional[Options]
useragent: Optional[str]

Create URL Scan

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)
{
  "api": "api",
  "message": "Submission successful",
  "result": "result",
  "url": "url",
  "uuid": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "visibility": "public",
  "options": {
    "useragent": "useragent"
  }
}
Returns Examples
{
  "api": "api",
  "message": "Submission successful",
  "result": "result",
  "url": "url",
  "uuid": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "visibility": "public",
  "options": {
    "useragent": "useragent"
  }
}