Search API Reference v1
Last updated: 2021-01-26


Our Search API & UI allows you to find archived scans of URLs on urlscan.io. This page is a reference for the available fields that can be used to query the API. Please see explanations about the field types and visibility below!

Query String Help

  • Search requests (either through the UI or API) are subject to your individual API Quotas.
  • The query field uses the ElasticSearch Query String to search for results.
  • All queries are run in filter mode, sorted by date descending. There is no scoring of search results.
  • Refer to the documentation for advanced queries such as wildcard, regex, boolean operators, fuzzy searches, etc.
  • You can group and concatenate search-terms with brackets
    ( )
    ,
    AND
    ,
    OR
    , and
    NOT
    . The default operator is
    AND
    .
  • You can concatenate terms within a group, e.g.
    page.domain:(foo.com OR bar.com)
    .
  • Always use the field names of the fields you want to search. Wildcards for the field-name are not supported!
  • Always escape reserved characters with backslash:
    + - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /
  • Always limit the time-range if possible using
    date
    , e.g.
    date:>now-7d
    or
    date:>now-1y
    .
  • You can use wildcard (leading wildcard only on urlscan Pro) and regex search on almost any field.
  • Regexes are always anchored to beginning/end of the tokens.
  • The
    date
    allows relative queries like
    date:>now-7d
    or range-queries like
    date:[2020-01-01 TO 2020-02-01]
    or both combined.
  • Domain fields contain the whole domain and each smaller domain component, i.e.
    domain
    can be searched by google.com which will include www.google.com

Supported Fields

The following fields are available in the Search API. Fields with a icon can be searched and are shown in the result. Fields with a can be searched as well, but their original value is not returned in the Search API results.

Field Name (+ Aliases) Type Plan Notes / Possible Values
task.time (date)dateWhen the URL was tasked
indexedAtdateTime the scan was last indexed in the search index
asnkeywordAny of the AS that were contacted (e.g. AS123)
asnnametextAny of the AS Names that were contacted
asnname.keywordkeywordAny of the AS Names that were contacted (analysed as keyword)
countrykeywordISO 3166-1 2-letter country code of any country that was contacted
domaindomainAny domain and subdomain that was contacted
filename (url)textAny URL that was requested
filename.keywordkeywordAny URL that was requested
hash (sha256)keywordAny SHA256 hash of any HTTP response
ipipAny IP that was contacted
serverkeywordAny HTTP "Server" header of subrequests
page.asnkeywordAS Number of the website
page.asnnametextName of the main AS of the website
page.citykeywordPrimary IP GeoIP City information
page.countrykeywordPrimary IP GeoIP Country (ISO 3166-1 2-letter country code)
page.domaindomainPrimary Domain (Analysed as all levels of parent domains)
page.domain.keywordkeywordPrimary Domain (Analysed as keyword)
page.ipipPrimary IP
page.ptrdomainDNS PTR record of primary IP
page.servertextHTTP "Server" header of primary request
page.statuskeywordHTTP status code of primary request response
page.urltextURL of the primary page (after redirection)
page.url.keywordkeywordURL of the primary page (after redirection, analysed as keyword)
stats.dataLengthintegerData size of all subresources
stats.encodedDataLengthintegerTransfer size of all subresources
stats.requestsshortNumber of subrequests
stats.uniqCountriesshortNumber of unique countries contacted
stats.uniqIPsshortNumber of unique IPs contacted
task.domaindomainDomain of the tasked URL
task.domain.keywordkeywordDomain of the tasked URL (analysed as keyword)
task.methodkeywordCan be manual, api or automatic
task.sourcekeywordExamples: phishtank or certstream-suspicious
task.tagskeywordCustom tags supplied during scan submission
task.urltextThe original URL that was tasked
task.url.keywordkeywordThe original URL that was tasked (analysed as keyword)
task.uuidkeywordThe unique UUID of the scan
task.visibilitykeywordCan be one of public, unlisted or private
uservirtualScans submitted by yourself (Can only be me)
teamvirtualScans submitted by any of your teams (Can only be me)
apikeyvirtualScans submitted using one of your API keys (Can only be me)
submitter.countrykeywordurlscan ProGeoIP country of the submission IP (ISO 3166-1 2-letter country code)
brand.countrykeywordurlscan ProISO 3166-1 2-letter country code of the brand
brand.keykeywordurlscan ProUnique key of the brand
brand.nametexturlscan ProName of the brand
brand.verticaltexturlscan ProIndustry vertical of the brand, e.g. "banking"

Field Type Help

The available search fields can have different types, which dictate how they can be searched. It is important to understand the limits of each type to fully utilise our Search API.

  • keyword — Field is analysed as one keyword, use the exact same value or a prefix search to search.
  • text — Field is analysed as text, broken into multiple tokens (e.g. split on slash in the URL).
  • date — Field is analysed as date, allowing range-queries and date math, e.g.
    date:>now-24h
    .
  • ip — Search by an IPv4 or IPv6, either using an exact IP or a subnet definition like
    ip:8.8.8.8\/24
    .
  • domain — Search by a domain or parent domain. You can search for
    www.foobar.com
    or just
    foobar.com
    and it will both find scans for www.foobar.com.
  • integer / short — Allows searchring by range, e.g.
    stats.uniqIPs:>5
    .