> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Saved queries and reports

> Save Attack Surface Query batches, run large exports as background report jobs, and render a saved query as a PDF report

## 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.

| Method and path | Permission | Purpose |
| - | - | - |
| `GET /api/attack-surface/saved-queries` | `report.read` | List the workspace's saved queries, by name |
| `POST /api/attack-surface/saved-queries` | `report.write` | Save a batch |
| `GET /api/attack-surface/saved-queries/:id` | `report.read` | Read one |
| `PATCH /api/attack-surface/saved-queries/:id` | `report.write` | Change its name, description or batch |
| `DELETE /api/attack-surface/saved-queries/:id` | `report.write` | Delete it |
| `POST /api/attack-surface/saved-queries/:id/run` | `report.read` | Run it and return the result, optionally with [params](#params) |

### Save a batch

```json theme={null}
{
  "name": "Weekly exposure review",
  "description": "New hosts, risky ports and open critical findings of the last 7 days",
  "spec": {
    "window": { "since": "now-7d" },
    "queries": {
      "newHosts": { "from": "hosts", "select": ["value", "kind", "target.value"], "limit": 200 },
      "riskyPorts": { "from": "services", "select": ["host.value", "port"], "limit": 200,
        "where": { "logic": "and", "items": [{ "field": "port", "op": "in", "value": ["21", "23", "445", "3389", "6379"] }] } },
      "critical": { "from": "vulnerabilities", "select": ["name", "host.value", "firstSeen"],
        "where": { "logic": "and", "items": [
          { "field": "isOpen", "op": "eq", "value": "true" },
          { "field": "severity", "op": "eq", "value": "critical" } ] } }
    }
  }
}
```

**name** `string` *required*

1 to 120 characters, unique in the workspace.

**description** `string`

Up to 2 000 characters.

**spec** `object` *required*

A batch: the same body as `POST /api/attack-surface/query`, plus an optional `params` declaration (see [Params](#params)).

The batch is validated when it is saved, against the catalog **and your permissions**: you cannot save a query over a resource you cannot read.

### 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 without `vulnerability.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 a `params` map to the spec, then put `{ "$param": "<name>" }` where a value should go:

```json theme={null}
{
  "name": "Exposure of one target",
  "spec": {
    "params": {
      "target": { "type": "string", "default": "example.com", "description": "Target to review" },
      "ports": { "type": "list", "default": ["21", "23", "445", "3389"] },
      "since": { "type": "string", "default": "now-7d" },
      "rows": { "type": "number", "default": 100 }
    },
    "window": { "since": { "$param": "since" } },
    "queries": {
      "exposed": {
        "from": "services",
        "select": ["host.value", "port", "http.title"],
        "where": { "logic": "and", "items": [
          { "field": "target.value", "op": "eq", "value": { "$param": "target" } },
          { "field": "port", "op": "in", "value": { "$param": "ports" } }
        ] },
        "limit": { "$param": "rows" }
      }
    }
  }
}
```

| `type` | Accepts | Typical use |
| - | - | - |
| `string` | a string, 1 to 255 characters | a filter value, a window bound (`now-7d`) |
| `number` | a number | a `limit`, or a numeric filter value (sent as its digits) |
| `list` | 1 to 100 strings | the value of `in`, `notIn`, `containsAny`… |

* A marker can stand for a **filter value**, a **`limit`** or 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.

```http theme={null}
POST /api/attack-surface/saved-queries/6f1d0c3a-…/run
Content-Type: application/json
X-Workspace-Id: <workspace id>

{ "params": { "target": "acme.io", "ports": ["3389"] } }
```

The values are put in place first, then the batch is validated like any other: a port that is not a number, or a target value that is too long, is refused with the path of the problem. A param the query does not declare is an error too.

[PDF reports](#pdf-reports) of a saved query use 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:

```json theme={null}
{
  "options": { "mode": "report" },
  "queries": {
    "allUrls": { "from": "urls", "select": ["url", "service.host.value", "firstSeen"], "limit": 20000, "window": null }
  }
}
```

Page the export with `nextCursor` as usual: each page is a new job.

The call returns at once:

```json theme={null}
{ "jobId": "0b6f2a4e-…", "status": "queued" }
```

Poll `GET /api/attack-surface/jobs/:jobId` until the job ends:

| `status` | Meaning |
| - | - |
| `queued` | Waiting for a worker; report jobs run one at a time per API instance |
| `running` | The batch is running |
| `completed` | `result` holds the batch result, the same shape as an interactive response |
| `failed` | `error` holds `{ code, message }` |

* The job state and its result are kept for **one hour** after the last update, then `GET …/jobs/:jobId` returns `NOT_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](https://docs.oasm.io/attack-surface-query/paging-and-limits.md#limits).
* 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](https://docs.oasm.io/reports.md):

```http theme={null}
POST /api/reports/generate/query
Content-Type: application/json
X-Workspace-Id: <workspace id>

{ "savedQueryId": "6f1d0c3a-…" }
```

* Requires `report.write`. The batch runs with your current permissions, and its [params](#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.mode` is 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.