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 -> { api, message, result, 4 more... }

post/accounts/{account_id}/urlscanner/v2/scan

Submit a URL to scan. Check limits at https://developers.cloudflare.com/security-center/investigate/scan-limits/.

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

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

path Parameters

account_id: string

Account ID.

scan_id: string

(format: uuid)

Scan UUID.

Response fields

data: { console, cookies, globals, 3 more... }

lists: { asns, certificates, continents, 7 more... }

meta: { processors }

page: { apexDomain, asn, asnname, 14 more... }

scanner: { colo, country }

stats: { domainStats, ipStats, IPv6Percentage, 10 more... }

task: { apexDomain, domain, domURL, 10 more... }

verdicts: { overall }

Request example

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/urlscanner/v2/result/$SCAN_ID \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY"

200Example

{
  "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": [
              {}
            ],
            "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"
          }
        ]
      },
      "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"
      ]
    }
  }
}

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