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.window is the default; allTimePorts opts out with "window": null.
Pattern 2: widen a row with related fields
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.”
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.”
Pattern 6: filter the included children
An include’s ownwhere limits which children are attached, without filtering the parents. “Every host, with only its admin-looking services.”
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 anid. 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.”"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 ownwhere 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.”
Cookbook
Targets and how many hosts each has
Targets and how many hosts each has
New domains and ports of the last 5 days
New domains and ports of the last 5 days
Risky services exposed
Risky services exposed
Login and admin pages
Login and admin pages
Hosts in a network range
Hosts in a network range
Technology versions in use
Technology versions in use
Where a CVE is present
Where a CVE is present
Hosts no scan has seen for 30 days
Hosts no scan has seen for 30 days
Findings per week by severity
Findings per week by severity
Certificates expiring within 30 days, wildcards first
Certificates expiring within 30 days, wildcards first
Services with no HTTP response
Services with no HTTP response
Production hosts only (exclude dev, staging and internal names)
Production hosts only (exclude dev, staging and internal names)
Findings that carry both of two CVEs
Findings that carry both of two CVEs
Hosts outside your known ranges
Hosts outside your known ranges
DNS records pointing to a provider
DNS records pointing to a provider
