urlscan.io Result API Reference v1
Last updated: 2022-02-17
The Result API allows retrieving the metadata generated by each scan. The metadata is a JSON object with different top-level keys. Some of the information in the object is redundant and only repeated for convenience. The best way to explore the available data in the Result API is to perform a scan and look at its API output.
April 20, 2022 - Result API warnings
- verdicts.XXX.score: This is an integer now which can range from -100 (legitimate) to 100 (malicious). Previously the range was 0-100.
- verdicts.overall.brands: This is a flat array of brand identifiers, contrary to verdicts.urlscan.brands which is an array of objects.
- verdicts.engines: This field is not used anymore and should not be relied on.
- Attention: Make sure your response parser can handle missing fields.
- Attention: If you use any of the detailed fields from the API result (especially within the data.requests list) then be prepared to adjust your code when data fields and formats change, or fields are added or removed. Many fields are not generated by us but by the Google Chrome webbrowser and as such may change over time without our intervention.
The Result API returns a JSON object for each scan which has the following top-level keys:
- Information about the submission: Time, method, options, links to screenshot/DOM
- High-level information about the page: Geolocation, IP, PTR
- Lists of domains, IPs, URLs, ASNs, servers, hashes
- All of the requests/responses, links, cookies, messages
- Processor output: ASN, GeoIP, AdBlock, Google Safe Browsing
- Computed stats (by type, protocol, IP, etc.)
- Verdicts about malicious content, with subkeys urlscan, engines, community.
You will notice that some fields are purely derivative (like the stats and lists) and made for easy consumption while other fields carry the raw data such as the "data" and "task" fields. The following is not a comprehensive list of all fields and sub-keys but should give you a good idea about where to look for what piece of information.
|Field Name||Type||Notes / Possible Values|
|task.uuid||UUIDv4||The unique ID of the scan|
|task.time||ISO-8601 timestamp||Time the scan was created|
|task.url||URL (String)||The URL that was tasked|
|task.visibility||String||Visibility of the task|
|task.method||String||The method of how the URL was tasked (api or manual or automatic)|
|task.tags||[String]||User-supplied tags submitted during submission|
|task.options||Object||Options supplied to the scan (not standardised yet)|
|page.url||URL (String)||The URL of the "primary request", i.e. the HTML document loaded last after all redirects|
|page.domain||String||Hostname from page.url|
|page.ip||IPv4 / IPv6||IP contacted for the primary request|
|page.ptr||IPv4 / IPv6||DNS PTR record for the primary IP|
|page.country||String||GeoIP Country Information about the IP contacted for the primary request|
|page.city||String||GeoIP City Information about the IP contacted for the primary request|
|page.server||String||HTTP "Server" header of the primary request response|
|page.asn||String||AS (Autonomous System) number of the primary IP|
|page.asnname||String||AS (Autonomous System) name of the primary IP|
|data.requests||[Object]||Individual HTTP transactions during page navigation (+ metadata)|
|data.cookies||[Object]||Cookies set by the page with associated metadata|
|data.console||[Object]||Console messages during page navigation|
|data.links||[Object]||Links and link text contained on the fully loaded page|
|data.timing||Object||Timing entries for various lifecycle events|
|meta.processors.asn.data||[Object]||IP ASN annotation for every IP contacted during page navigation|
|meta.processors.download.data||[Object]||List of files that were downloaded by the website.
Keys: filename, filesize, receivedBytes, url, startedAt, state, mimeType, mimeDescription, sha256, finishedAt
|meta.processors.geoip.data||[Object]||GeoIP annotation for every IP contacted during page navigation|
|meta.processors.rdns.data||[Object]||DNS PTR records for every hostname contacted during page navigation|
|meta.processors.umbrella.data||[Object]||Cisco Umbrella Top 1 Million annotation per hostname|
|meta.processors.wappa.data||[Object]||Wappalyzer technology detection for fully loaded page|
|lists.countries||[ISO-3166]||GeoIP country of IPs contacted|
|lists.asns||[Integer]||AS Numbers contacted|
|lists.server||[String]||Unique HTTP "Server" headers of responses|
|lists.linkDomains||[String]||Unique hostnames of links|
|lists.certificates||[Object]||TLS Certificates of responses|
|lists.hashes||[String]||SHA256s hashes of HTTP response bodies|
|verdicts.urlscan.score||Integer||Maliciousness score (-100 to 100, with -100 being legitimate and 100 being malicious)|
|verdicts.urlscan.categories||[String]||Maliciousness categories (e.g. "phishing")|
|verdicts.urlscan.brands.country||[String]||Brand countries (ISO-3166)|
|verdicts.urlscan.brands.vertical||[String]||Brand industry verticals|