Saved queries
A saved query is a named batch stored in the workspace, so a team can rerun the same questions — a weekly exposure review, a compliance export — without copying JSON around.Save a batch
A batch: the same body as
POST /api/attack-surface/query, plus an optional params declaration (see Params).Running a saved query
A saved query always runs as the member who runs it, with their permissions at that moment — not the author’s. A member withoutvulnerability.read who runs the batch above gets PERMISSION_DENIED. The batch is validated again on every run, so a saved query keeps following any change to your role.
Relative times (now-7d) are resolved when the query runs, so a saved weekly review always covers the last seven days.
Params
Often the same question is asked about different things: what is exposed on this target?, which hosts run this port?. Rather than saving one copy per target, save the query once with params and fill them in when you run it.Declare them
Add aparams map to the spec, then put { "$param": "<name>" } where a value should go:
- A marker can stand for a filter value, a
limitor a window bound (since,until), nowhere else: never for a field, an operator or a resource. A param can change what you look for, not what the query reads. - Every param needs a
default. The spec is validated with the defaults when you save it, so a saved query always runs as it is. - A saved query holds at most 10 params, and every declared param must be used.
Run with values
Send the values in the body of the run call. Missing ones take their default; no body at all runs everything with the defaults.Report mode
For exports larger than an interactive query allows, send the batch with"options": { "mode": "report" }. It is queued as a background job instead of running in the request:
nextCursor as usual: each page is a new job.
The call returns at once:
GET /api/attack-surface/jobs/:jobId until the job ends:
- The job state and its result are kept for one hour after the last update, then
GET …/jobs/:jobIdreturnsNOT_FOUND. - The batch is validated and costed before it is queued, so a mistake is reported at once, not in the job.
- The job runs with your permissions as they were when you queued it. A failed job is not retried.
- Report mode raises the limits: 50 000 rows per query, 120 s per statement, 10 minutes per batch, 16 MB of response and a cost budget of 60 000. See Paging, limits and cost.
- When the operator sets
ASQ_READ_REPLICA_URL, report jobs read from that read replica, keeping heavy exports off the primary database. - Report mode is available through the HTTP API only, not to the AI agent or MCP clients (
MODE_CONFLICT).
PDF reports
A saved query can be rendered as a PDF and stored with the workspace’s other reports:- Requires
report.write. The batch runs with your current permissions, and its params at their defaults. - All queries of the batch read one consistent database snapshot, so the numbers of the tables agree with each other.
- The batch runs under the interactive limits (1 000 rows per query, cost budget 1 000); its own
options.modeis ignored. - Each query becomes one table, named after the query. Related fields become columns (
host.value); lists of related rows are shown as the first value of each child, comma-separated; ids are left out. - A table holds at most 500 rows and a cell at most 300 characters. A table that was cut, or whose query had more pages, is marked as truncated.
- A query that fails shows its error in place of its table; the other tables are still rendered.
