Skip to main content
The building blocks — select, include, where, windows and aggregates — combine freely. This page starts from questions people actually ask and shows the pattern behind each answer, then a cookbook of complete batches you can paste into the API.

Pattern 1: batch the questions

Put every part of a question into one batch. Queries run in parallel, and one failing query does not stop the others.
The batch window is the default; allTimePorts opts out with "window": null. Start from the resource the question is about and pull the context through dot paths. “Which TLS certificates expire this month, on which host and port, and what does the site say?”

Pattern 3: filter on one thing, return another

where can test related rows and lists the result does not show. “Services running WordPress on a host that has a critical finding.”
A filter path may go through related rows before and after a list (host.vulnerabilities.severity, services.http.title), but through one list at most: services.technologies.name from hosts is refused. Start from the resource one list closer instead, as above.
Each list condition is checked on its own: the host has some critical finding, not necessarily an open one even if you add host.vulnerabilities.isOpen as a second condition. To tie several conditions to the same related row, use a relation test (pattern 9), or query that row’s resource instead (pattern 4).

Pattern 4: query the child, not the parent

When the question is about the children, read them directly and pull the parent through a related field. This is also the way out of an include that is too large. “Every service running an outdated nginx, with its host.”

Pattern 5: one row with everything around it

include attaches lists to each row; nest them to go two levels down. Keep the parent limit small. “Everything known about api.example.com.”
The IPs are a second query of the same batch rather than a third include: a query has at most five includes in total (three for the AI agent), nested ones included.

Pattern 6: filter the included children

An include’s own where limits which children are attached, without filtering the parents. “Every host, with only its admin-looking services.”
To keep only the hosts that have such a service, add the same condition to the parent’s where as a list path:

Pattern 7: list and count together

A list and its distribution are two queries of one batch, with the same filter.

Pattern 8: follow up with ids

Every row carries an id. Use it in the next batch to drill down, or pass it to other OASM APIs.

Pattern 9: ask about what is missing

Some of the most useful security questions are about absence: a host that serves HTTP but not HTTPS, a target with no host left, a service nobody has fingerprinted. Relation tests say that directly. “Hosts that answer on port 80 but have nothing on 443.”
The same shape covers every ("quantifier": "every": all of a host’s ports are web ports) and how many ("count": { "op": "gte", "value": "10" }: hosts with ten open ports or more).

Pattern 10: a matrix in one query

When a table needs a column per category, give each aggregate its own where instead of running one query per category. Then keep only the interesting rows with having. “Targets ranked by open critical and high findings, only those that have any.”

Pattern 11: a chart without holes

A series for a chart needs one point per day, including quiet days, in the viewer’s time zone. fill and options.timezone give exactly that. “New ports and new findings per day over the last 30 days, Hanoi time.”
Both series have the same days in the same order, so they line up on one chart.

Cookbook