General Instructions

Each API endpoint provides its own set of search features, with all supported parameters detailed on the corresponding documentation page. The following general search rules apply universally across all endpoints.

Query String Syntax and General Instructions

• Search requests (through the UI or API) are subject to your individual Search API quotas. Make sure to use your API key.
• The query field uses the ElasticSearch Query String to search for results.
• All queries are run in filter mode, sorted by date with the most recent scans first. There is no scoring of search results.
• 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. Field names are case sensitive.
• Always escape reserved characters with backslash: + - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /
• Limit the time-range if possible using the relevant date filter, e.g., date:>now-7d or date:>now-1y.
• The date allows relative queries like date:>now-7d, range queries like date:[2020-01-01 TO 2020-02-01], or a combination of both.
• You can only use leading wildcard searches and regular expression searches on supported fields, and only as a signed-in user.
• Everything is indexed as lowercase, even if the Search API returns values in a case-preserving manner.
• Regular expressions are always anchored to beginning/end of the tokens (implicit ^ and $). Make sure to prefix/suffix with .* to match infix strings.
• Domain fields contain the whole domain and each smaller domain component, e.g., domain can be searched by google.com which will find hits for www.google.com.

Field Type Legend

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 utilize our Search API.

• keyword — Field is analyzed as one keyword, use an exact value or a trailing wildcard search to search. Indexed as lowercase.
• keyword RE — Field can be searched by regular expression or leading wildcard. Indexed as lowercase.
• text — Field is analyzed as text, broken into multiple tokens (e.g., split on slash in the URL). Phrase search with quotes possible. Indexed as lowercase.
• date — Field is analyzed as date, allowing range queries and date math, e.g., date:>now-24h.
• ip — Search by an IPv4 or IPv6 address, either by 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 — Allows searching by exact value, range, or threshold, e.g., stats.uniqIPs:>5.