The batch
A request is a batch of named queries:One to ten named queries. A name starts with a letter and contains letters, digits and
_ (at most 64 characters). Results come back under the same names.Default time window of every query that does not set its own:
{ "since": "now-7d", "until": "now" }. See Time windows.Run every query of the batch on one database snapshot, one after the other. Use it when the numbers of several queries must add up exactly (a report); otherwise queries run in parallel.
interactive runs the batch now. report queues it as a background job with much larger limits. See Saved queries and reports.IANA time zone that time buckets (
day, week…) are cut in, e.g. Asia/Ho_Chi_Minh. See Time zones.A query
The resource to read:
targets, hosts, services, technologies, tls, urls, ips, dnsRecords, vulnerabilities or rollups.Fields to return. Omit it for a small default set (for
services: port, host.value, firstSeen).Lists of related rows to attach to each row. See include.
Filter. See Filtering.
Turn the query into a count. See Counting and grouping.
Filter on the groups of an aggregate query, by group key or aggregate name. See having.
Return every time bucket of the window, empty ones included. See Filling empty buckets.
Rows per page. See Paging, limits and cost for the maximum.
select: fields and related rows
A field is either a field of the resource (port) or a field of a single related row, written as a dot path. A service has one host, one target and one latest HTTP response, so all of these are valid on services:
technologies → service → host gives service.host.value.
include: lists of related rows
A host has many services; a service has many technologies and URLs. A list cannot go inselect — attach it with include. Each include is a small query of its own:
Filter on the child rows: only matching children are attached. The parent rows are not filtered by it (use the parent’s
where for that).Order of the children. Only some fields can order a list (for example
firstSeen, and port for a host’s services); the others keep a natural order.Lists of each resource
Default fields and order
A default field you are not allowed to read (for example
target.value without target.read) is left out instead of failing the query.