API Reference

URL Scanner

Scans

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create URL Scan

client.URLScanner.Scans.New(ctx, params) (*ScanNewResponse, error)

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

params ScanNewParams

AccountID param.Field[string]

Path param: Account ID.

URL param.Field[string]

Body param

AgentReadiness param.Field[bool]Optional

Body param: Enable agent readiness checks.

Country param.Field[ScanNewParamsCountry]Optional

Body param: Country to geo egress from

const ScanNewParamsCountryAe ScanNewParamsCountry = "AE"

const ScanNewParamsCountryAl ScanNewParamsCountry = "AL"

const ScanNewParamsCountryAm ScanNewParamsCountry = "AM"

const ScanNewParamsCountryAo ScanNewParamsCountry = "AO"

const ScanNewParamsCountryAr ScanNewParamsCountry = "AR"

const ScanNewParamsCountryAt ScanNewParamsCountry = "AT"

const ScanNewParamsCountryAu ScanNewParamsCountry = "AU"

const ScanNewParamsCountryAz ScanNewParamsCountry = "AZ"

const ScanNewParamsCountryBb ScanNewParamsCountry = "BB"

const ScanNewParamsCountryBd ScanNewParamsCountry = "BD"

const ScanNewParamsCountryBe ScanNewParamsCountry = "BE"

const ScanNewParamsCountryBf ScanNewParamsCountry = "BF"

const ScanNewParamsCountryBg ScanNewParamsCountry = "BG"

const ScanNewParamsCountryBh ScanNewParamsCountry = "BH"

const ScanNewParamsCountryBn ScanNewParamsCountry = "BN"

const ScanNewParamsCountryBo ScanNewParamsCountry = "BO"

const ScanNewParamsCountryBr ScanNewParamsCountry = "BR"

const ScanNewParamsCountryBt ScanNewParamsCountry = "BT"

const ScanNewParamsCountryBw ScanNewParamsCountry = "BW"

const ScanNewParamsCountryBy ScanNewParamsCountry = "BY"

const ScanNewParamsCountryCA ScanNewParamsCountry = "CA"

const ScanNewParamsCountryCd ScanNewParamsCountry = "CD"

const ScanNewParamsCountryCh ScanNewParamsCountry = "CH"

const ScanNewParamsCountryCi ScanNewParamsCountry = "CI"

const ScanNewParamsCountryCl ScanNewParamsCountry = "CL"

const ScanNewParamsCountryCm ScanNewParamsCountry = "CM"

const ScanNewParamsCountryCo ScanNewParamsCountry = "CO"

const ScanNewParamsCountryCr ScanNewParamsCountry = "CR"

const ScanNewParamsCountryCw ScanNewParamsCountry = "CW"

const ScanNewParamsCountryCy ScanNewParamsCountry = "CY"

const ScanNewParamsCountryCz ScanNewParamsCountry = "CZ"

const ScanNewParamsCountryDe ScanNewParamsCountry = "DE"

const ScanNewParamsCountryDj ScanNewParamsCountry = "DJ"

const ScanNewParamsCountryDK ScanNewParamsCountry = "DK"

const ScanNewParamsCountryDo ScanNewParamsCountry = "DO"

const ScanNewParamsCountryDz ScanNewParamsCountry = "DZ"

const ScanNewParamsCountryEc ScanNewParamsCountry = "EC"

const ScanNewParamsCountryEe ScanNewParamsCountry = "EE"

const ScanNewParamsCountryEg ScanNewParamsCountry = "EG"

const ScanNewParamsCountryEs ScanNewParamsCountry = "ES"

const ScanNewParamsCountryEt ScanNewParamsCountry = "ET"

const ScanNewParamsCountryFi ScanNewParamsCountry = "FI"

const ScanNewParamsCountryFj ScanNewParamsCountry = "FJ"

const ScanNewParamsCountryFr ScanNewParamsCountry = "FR"

const ScanNewParamsCountryGB ScanNewParamsCountry = "GB"

const ScanNewParamsCountryGd ScanNewParamsCountry = "GD"

const ScanNewParamsCountryGe ScanNewParamsCountry = "GE"

const ScanNewParamsCountryGh ScanNewParamsCountry = "GH"

const ScanNewParamsCountryGr ScanNewParamsCountry = "GR"

const ScanNewParamsCountryGt ScanNewParamsCountry = "GT"

const ScanNewParamsCountryGu ScanNewParamsCountry = "GU"

const ScanNewParamsCountryGy ScanNewParamsCountry = "GY"

const ScanNewParamsCountryHk ScanNewParamsCountry = "HK"

const ScanNewParamsCountryHn ScanNewParamsCountry = "HN"

const ScanNewParamsCountryHr ScanNewParamsCountry = "HR"

const ScanNewParamsCountryHt ScanNewParamsCountry = "HT"

const ScanNewParamsCountryHu ScanNewParamsCountry = "HU"

const ScanNewParamsCountryID ScanNewParamsCountry = "ID"

const ScanNewParamsCountryIe ScanNewParamsCountry = "IE"

const ScanNewParamsCountryIl ScanNewParamsCountry = "IL"

const ScanNewParamsCountryIn ScanNewParamsCountry = "IN"

const ScanNewParamsCountryIq ScanNewParamsCountry = "IQ"

const ScanNewParamsCountryIs ScanNewParamsCountry = "IS"

const ScanNewParamsCountryIt ScanNewParamsCountry = "IT"

const ScanNewParamsCountryJm ScanNewParamsCountry = "JM"

const ScanNewParamsCountryJo ScanNewParamsCountry = "JO"

const ScanNewParamsCountryJp ScanNewParamsCountry = "JP"

const ScanNewParamsCountryKe ScanNewParamsCountry = "KE"

const ScanNewParamsCountryKg ScanNewParamsCountry = "KG"

const ScanNewParamsCountryKh ScanNewParamsCountry = "KH"

const ScanNewParamsCountryKr ScanNewParamsCountry = "KR"

const ScanNewParamsCountryKw ScanNewParamsCountry = "KW"

const ScanNewParamsCountryKz ScanNewParamsCountry = "KZ"

const ScanNewParamsCountryLa ScanNewParamsCountry = "LA"

const ScanNewParamsCountryLB ScanNewParamsCountry = "LB"

const ScanNewParamsCountryLk ScanNewParamsCountry = "LK"

const ScanNewParamsCountryLr ScanNewParamsCountry = "LR"

const ScanNewParamsCountryLt ScanNewParamsCountry = "LT"

const ScanNewParamsCountryLu ScanNewParamsCountry = "LU"

const ScanNewParamsCountryLv ScanNewParamsCountry = "LV"

const ScanNewParamsCountryMa ScanNewParamsCountry = "MA"

const ScanNewParamsCountryMd ScanNewParamsCountry = "MD"

const ScanNewParamsCountryMg ScanNewParamsCountry = "MG"

const ScanNewParamsCountryMk ScanNewParamsCountry = "MK"

const ScanNewParamsCountryMm ScanNewParamsCountry = "MM"

const ScanNewParamsCountryMn ScanNewParamsCountry = "MN"

const ScanNewParamsCountryMo ScanNewParamsCountry = "MO"

const ScanNewParamsCountryMt ScanNewParamsCountry = "MT"

const ScanNewParamsCountryMu ScanNewParamsCountry = "MU"

const ScanNewParamsCountryMv ScanNewParamsCountry = "MV"

const ScanNewParamsCountryMw ScanNewParamsCountry = "MW"

const ScanNewParamsCountryMX ScanNewParamsCountry = "MX"

const ScanNewParamsCountryMy ScanNewParamsCountry = "MY"

const ScanNewParamsCountryMz ScanNewParamsCountry = "MZ"

const ScanNewParamsCountryNa ScanNewParamsCountry = "NA"

const ScanNewParamsCountryNc ScanNewParamsCountry = "NC"

const ScanNewParamsCountryNg ScanNewParamsCountry = "NG"

const ScanNewParamsCountryNl ScanNewParamsCountry = "NL"

const ScanNewParamsCountryNo ScanNewParamsCountry = "NO"

const ScanNewParamsCountryNp ScanNewParamsCountry = "NP"

const ScanNewParamsCountryNz ScanNewParamsCountry = "NZ"

const ScanNewParamsCountryOm ScanNewParamsCountry = "OM"

const ScanNewParamsCountryPa ScanNewParamsCountry = "PA"

const ScanNewParamsCountryPe ScanNewParamsCountry = "PE"

const ScanNewParamsCountryPf ScanNewParamsCountry = "PF"

const ScanNewParamsCountryPh ScanNewParamsCountry = "PH"

const ScanNewParamsCountryPk ScanNewParamsCountry = "PK"

const ScanNewParamsCountryPl ScanNewParamsCountry = "PL"

const ScanNewParamsCountryPr ScanNewParamsCountry = "PR"

const ScanNewParamsCountryPs ScanNewParamsCountry = "PS"

const ScanNewParamsCountryPt ScanNewParamsCountry = "PT"

const ScanNewParamsCountryPy ScanNewParamsCountry = "PY"

const ScanNewParamsCountryQa ScanNewParamsCountry = "QA"

const ScanNewParamsCountryRe ScanNewParamsCountry = "RE"

const ScanNewParamsCountryRo ScanNewParamsCountry = "RO"

const ScanNewParamsCountryRs ScanNewParamsCountry = "RS"

const ScanNewParamsCountryRu ScanNewParamsCountry = "RU"

const ScanNewParamsCountryRw ScanNewParamsCountry = "RW"

const ScanNewParamsCountrySa ScanNewParamsCountry = "SA"

const ScanNewParamsCountrySe ScanNewParamsCountry = "SE"

const ScanNewParamsCountrySg ScanNewParamsCountry = "SG"

const ScanNewParamsCountrySi ScanNewParamsCountry = "SI"

const ScanNewParamsCountrySk ScanNewParamsCountry = "SK"

const ScanNewParamsCountrySn ScanNewParamsCountry = "SN"

const ScanNewParamsCountrySr ScanNewParamsCountry = "SR"

const ScanNewParamsCountryTh ScanNewParamsCountry = "TH"

const ScanNewParamsCountryTj ScanNewParamsCountry = "TJ"

const ScanNewParamsCountryTn ScanNewParamsCountry = "TN"

const ScanNewParamsCountryTr ScanNewParamsCountry = "TR"

const ScanNewParamsCountryTt ScanNewParamsCountry = "TT"

const ScanNewParamsCountryTw ScanNewParamsCountry = "TW"

const ScanNewParamsCountryTz ScanNewParamsCountry = "TZ"

const ScanNewParamsCountryUA ScanNewParamsCountry = "UA"

const ScanNewParamsCountryUg ScanNewParamsCountry = "UG"

const ScanNewParamsCountryUs ScanNewParamsCountry = "US"

const ScanNewParamsCountryUz ScanNewParamsCountry = "UZ"

const ScanNewParamsCountryVn ScanNewParamsCountry = "VN"

const ScanNewParamsCountryZa ScanNewParamsCountry = "ZA"

const ScanNewParamsCountryZm ScanNewParamsCountry = "ZM"

const ScanNewParamsCountryZw ScanNewParamsCountry = "ZW"

Customagent param.Field[string]Optional

Body param

maxLength4096

CustomHeaders param.Field[map[string, string]]Optional

Body param: Set custom headers.

Referer param.Field[string]Optional

Body param

maxLength4096

ScreenshotsResolutions param.Field[[]ScanNewParamsScreenshotsResolution]Optional

Body param: Take multiple screenshots targeting different device types.

const ScanNewParamsScreenshotsResolutionDesktop ScanNewParamsScreenshotsResolution = "desktop"

const ScanNewParamsScreenshotsResolutionMobile ScanNewParamsScreenshotsResolution = "mobile"

const ScanNewParamsScreenshotsResolutionTablet ScanNewParamsScreenshotsResolution = "tablet"

Visibility param.Field[ScanNewParamsVisibility]Optional

Body param: 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.

const ScanNewParamsVisibilityPublic ScanNewParamsVisibility = "Public"

const ScanNewParamsVisibilityUnlisted ScanNewParamsVisibility = "Unlisted"

ReturnsExpand Collapse

type ScanNewResponse struct{…}

API string

URL to api report.

Message string

Result string

Public URL to report.

URL string

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

UUID string

Scan ID.

formatuuid

Visibility ScanNewResponseVisibility

Submitted visibility status.

One of the following:

const ScanNewResponseVisibilityPublic ScanNewResponseVisibility = "public"

const ScanNewResponseVisibilityUnlisted ScanNewResponseVisibility = "unlisted"

Options ScanNewResponseOptionsOptional

Useragent stringOptional

Create URL Scan

Go

HTTP

TypeScript

Python

Go

Terraform

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/option"
  "github.com/cloudflare/cloudflare-go/url_scanner"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  scan, err := client.URLScanner.Scans.New(context.TODO(), url_scanner.ScanNewParams{
    AccountID: cloudflare.F("account_id"),
    URL: cloudflare.F("https://www.example.com"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", scan.UUID)
}

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"
  }
}