Skip to main content

The batch

A request is a batch of named queries:
object
required
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.
object
Default time window of every query that does not set its own: { "since": "now-7d", "until": "now" }. See Time windows.
boolean
default:"false"
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.
string
default:"interactive"
interactive runs the batch now. report queues it as a background job with much larger limits. See Saved queries and reports.
string
default:"UTC"
IANA time zone that time buckets (day, week…) are cut in, e.g. Asia/Ho_Chi_Minh. See Time zones.
Every object is strict: an unknown key anywhere (a typo such as "selct", or a workspaceId) is an error, not ignored. The workspace always comes from your session, never from the body.

A query

string
required
The resource to read: targets, hosts, services, technologies, tls, urls, ips, dnsRecords, vulnerabilities or rollups.
string[]
Fields to return. Omit it for a small default set (for services: port, host.value, firstSeen).
object
Lists of related rows to attach to each row. See include.
object
Filter. See Filtering.
object | null
Time window of this query; overrides the batch’s. null means all time.
string
The time field the window applies to. Default: the resource’s firstSeen.
array / object
Turn the query into a count. See Counting and grouping.
object
Filter on the groups of an aggregate query, by group key or aggregate name. See having.
boolean
default:"false"
Return every time bucket of the window, empty ones included. See Filling empty buckets.
object[]
Up to three { "field", "dir": "asc" | "desc" }. Default: newest first.
number
default:"50"
Rows per page. See Paging, limits and cost for the maximum.
string
The nextCursor of the previous page.
boolean
default:"false"
Also return total, the number of matching rows (capped at 10 000).
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:
The result nests the related fields:
Paths can chain two related rows: technologies → service → host gives service.host.value.
A related row that does not exist comes back as null, not as an object of nulls: "http": null means the service has no HTTP response.
A host has many services; a service has many technologies and URLs. A list cannot go in select — attach it with include. Each include is a small query of its own:
string[]
Fields of the child rows (and their related rows).
object
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).
object[]
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.
number
default:"10"
Children per parent row (at most 50; 20 for the AI agent).
object
Nested lists, two levels deep at most.
Each include fetches up to its own limit for every row: 200 hosts × 20 services is 4 000 child rows. Keep limit × include limit small, or query the child resource directly with a filter (see Composing queries).

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.