--- title: Create URL Scan --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api) [URL Scanner](https://developers.cloudflare.com/api/resources/url_scanner) [Scans](https://developers.cloudflare.com/api/resources/url_scanner/subresources/scans) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Create URL Scan 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 Write``URL Scanner Read` ##### P ath ParametersExpand Collapse account\_id: string Account ID. [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%20default%20%3E%20(param)%20account_id%20%3E%20(schema)>) ##### Body ParametersJSONExpand Collapse url: string [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20url%20%3E%20(schema)>) agentReadiness: optional boolean Enable agent readiness checks. [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20agentReadiness%20%3E%20(schema)>)

country: optional "AF"or "AL"or "DZ"or 192 more Country to geo egress from

[Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20country%20%3E%20(schema)>) customagent: optional string maxLength4096 [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20customagent%20%3E%20(schema)>) customHeaders: optional map\[string] Set custom headers. [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20customHeaders%20%3E%20(schema)>) referer: optional string maxLength4096 [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20referer%20%3E%20(schema)>)

screenshotsResolutions: optional array of "desktop"or "mobile"or "tablet" Take multiple screenshots targeting different device types.

One of the following: "desktop" Link to this property "mobile" Link to this property "tablet" Link to this property

[Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20screenshotsResolutions%20%3E%20(schema)>)

visibility: optional "Public"or "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" Link to this property "Unlisted" Link to this property

[Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20visibility%20%3E%20(schema)>) ##### ReturnsExpand Collapse api: string URL to api report. [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(model)%20scan_create_response%20%3E%20(schema)%20%3E%20(property)%20api>) message: string [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(model)%20scan_create_response%20%3E%20(schema)%20%3E%20(property)%20message>) result: string Public URL to report. [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(model)%20scan_create_response%20%3E%20(schema)%20%3E%20(property)%20result>) url: string Canonical form of submitted URL. Use this if you want to later search by URL. [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(model)%20scan_create_response%20%3E%20(schema)%20%3E%20(property)%20url>) uuid: string Scan ID. formatuuid [Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(model)%20scan_create_response%20%3E%20(schema)%20%3E%20(property)%20uuid>)

visibility: "public"or "unlisted" Submitted visibility status.

One of the following: "public" Link to this property "unlisted" Link to this property

[Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(model)%20scan_create_response%20%3E%20(schema)%20%3E%20(property)%20visibility>)

options: optional object {useragent }

useragent: optional string Link to this property

[Link to this property](<#(resource)%20url_scanner.scans%20%3E%20(model)%20scan_create_response%20%3E%20(schema)%20%3E%20(property)%20options>) ### Create URL Scan HTTP HTTPTypeScriptPythonGoTerraform ``` curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/urlscanner/v2/scan \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ -d '{ "url": "https://www.example.com" }' ``` 200 example ``` { "api": "api", "message": "Submission successful", "result": "result", "url": "url", "uuid": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "visibility": "public", "options": { "useragent": "useragent" } } ``` ##### Returns Examples 200 example ``` { "api": "api", "message": "Submission successful", "result": "result", "url": "url", "uuid": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "visibility": "public", "options": { "useragent": "useragent" } } ```