Cloudflare API | URL Scanner › Scans

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.

Create URL Scan -> Envelope<string>

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

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

Example: Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

Accepted Permissions (at least one required)

URL Scanner Write URL Scanner Read

Parameters

account_id: string

Account ID.

Body parameters

url: string

customagent: string

Optional

(maxLength: 4096)

customHeaders: Record<string, string>

Optional

Set custom headers.

referer: string

Optional

(maxLength: 4096)

screenshotsResolutions: Array<"desktop" | "mobile" | "tablet">

Optional

Take multiple screenshots targeting different device types.

visibility: "Public" | "Unlisted"

Optional

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.

Response fields

api: string

URL to api report.

message: string

result: string

URL to report.

url: string

Canonical form of submitted URL. Use this if you want to later search by URL.

uuid: string

(format: uuid)

Scan ID.

visibility: string

Submitted visibility status.

options: { useragent }

Optional

Request example

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/urlscanner/v2/scan \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
      "url": "https://www.example.com"
    }'

200Example

{
  "api": "api",
  "message": "Submission successful",
  "result": "result",
  "url": "url",
  "uuid": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "visibility": "Public",
  "options": {
    "useragent": "useragent"
  }
}

Get URL Scan S DOM -> string

get/accounts/{account_id}/urlscanner/v2/dom/{scan_id}

Returns a plain text response, with the scan's DOM content as rendered by Chrome.

Get URL Scan -> { data, lists, meta, 5 more... }

get/accounts/{account_id}/urlscanner/v2/result/{scan_id}

Get URL scan by uuid

Get URL Scan S HAR -> { log }

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

Search URL Scans -> { results }

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.

Get Screenshot -> unknown

get/accounts/{account_id}/urlscanner/v2/screenshots/{scan_id}.png

Get scan's screenshot by resolution (desktop/mobile/tablet).