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

# Query structure

> The parts of an Attack Surface Query: the batch, from, select, related rows, include and the response shape

## The batch

A request is a **batch** of named queries:

```json theme={null}
{
  "window": { "since": "now-7d" },
  "queries": {
    "<name>": { "from": "<resource>", "...": "..." },
    "<another name>": { "from": "<resource>", "...": "..." }
  },
  "options": { "consistent": false, "mode": "interactive", "timezone": "UTC" }
}
```

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

**window** `object`

Default time window of every query that does not set its own: `{ "since": "now-7d", "until": "now" }`. See [Time windows](https://docs.oasm.io/attack-surface-query/filtering.md#time-windows).

**options.consistent** `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.

**options.mode** `string` (default: interactive)

`interactive` runs the batch now. `report` queues it as a background job with much larger limits. See [Saved queries and reports](https://docs.oasm.io/attack-surface-query/saved-queries-and-reports.md#report-mode).

**options.timezone** `string` (default: UTC)

IANA time zone that time buckets (`day`, `week`…) are cut in, e.g. `Asia/Ho_Chi_Minh`. See [Time zones](https://docs.oasm.io/attack-surface-query/aggregations.md#time-zones).

> [!WARNING]
>
> 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

**from** `string` *required*

The resource to read: `targets`, `hosts`, `services`, `technologies`, `tls`, `urls`, `ips`, `dnsRecords`, `vulnerabilities` or `rollups`.

**select** `string[]`

Fields to return. Omit it for a small default set (for `services`: `port`, `host.value`, `firstSeen`).

**include** `object`

Lists of related rows to attach to each row. See [include](#include-lists-of-related-rows).

**where** `object`

Filter. See [Filtering](https://docs.oasm.io/attack-surface-query/filtering.md).

**window** `object | null`

Time window of this query; overrides the batch's. `null` means all time.

**windowField** `string`

The time field the window applies to. Default: the resource's `firstSeen`.

**groupBy / aggregate** `array / object`

Turn the query into a count. See [Counting and grouping](https://docs.oasm.io/attack-surface-query/aggregations.md).

**having** `object`

Filter on the groups of an aggregate query, by group key or aggregate name. See [having](https://docs.oasm.io/attack-surface-query/aggregations.md#having-filter-the-groups).

**fill** `boolean` (default: false)

Return every time bucket of the window, empty ones included. See [Filling empty buckets](https://docs.oasm.io/attack-surface-query/aggregations.md#filling-empty-buckets).

**orderBy** `object[]`

Up to three `{ "field", "dir": "asc" | "desc" }`. Default: newest first.

**limit** `number` (default: 50)

Rows per page. See [Paging, limits and cost](https://docs.oasm.io/attack-surface-query/paging-and-limits.md) for the maximum.

**cursor** `string`

The `nextCursor` of the previous page.

**withTotal** `boolean` (default: false)

Also return `total`, the number of matching rows (capped at 10 000).

## select: fields and related rows

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`:

```json theme={null}
{ "from": "services", "select": ["port", "host.value", "target.value", "http.title", "http.statusCode"] }
```

The result nests the related fields:

```json theme={null}
{
  "id": "53c80e50-…",
  "port": 443,
  "host": { "value": "api.example.com" },
  "target": { "value": "example.com" },
  "http": { "title": "API Gateway", "statusCode": 200 }
}
```

Paths can chain two related rows: `technologies` → `service` → `host` gives `service.host.value`.

> [!TIP]
>
> 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.

## include: lists of related rows

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:

```json theme={null}
{
  "from": "hosts",
  "select": ["value"],
  "limit": 20,
  "include": {
    "services": {
      "select": ["port", "http.title"],
      "limit": 10,
      "include": {
        "technologies": { "select": ["name", "version"], "limit": 5 }
      }
    }
  }
}
```

```json theme={null}
{
  "id": "1396ad91-…",
  "value": "api.example.com",
  "services": [
    { "id": "…", "port": 443, "http": { "title": "API Gateway" },
      "technologies": [ { "id": "…", "name": "nginx", "version": "1.25" } ] }
  ]
}
```

**include.\<list>.select** `string[]`

Fields of the child rows (and their related rows).

**include.\<list>.where** `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).

**include.\<list>.orderBy** `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.

**include.\<list>.limit** `number` (default: 10)

Children per parent row (at most 50; 20 for the AI agent).

**include.\<list>.include** `object`

Nested lists, two levels deep at most.

> [!WARNING]
>
> 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](https://docs.oasm.io/attack-surface-query/composing-queries.md)).

### Lists of each resource

| Resource | Single related rows (`select` with a dot) | Lists (`include`, or `where`) |
| - | - | - |
| `targets` | – | `hosts` |
| `hosts` | `target` | `services`, `ips`, `dnsRecords`, `vulnerabilities` |
| `services` | `host`, `target`, `http` | `technologies`, `tls`, `statusCodes`, `urls`, `tags` |
| `technologies`, `tls`, `urls` | `service` | – |
| `ips`, `dnsRecords` | `host` | – |
| `vulnerabilities` | `host`, `tool` | – |

## Default fields and order

| Resource | Default `select` | Default order |
| - | - | - |
| `targets` | `value`, `type`, `firstSeen` | newest first |
| `hosts` | `value`, `kind`, `firstSeen`, `target.value` | newest first |
| `services` | `port`, `host.value`, `firstSeen` | newest first |
| `technologies` | `name`, `version`, `service.host.value`, `service.port` | newest first |
| `tls` | `host`, `port`, `notAfter`, `issuerCn` | `notAfter` ascending (expiring first) |
| `urls` | `url`, `firstSeen` | newest first |
| `ips` | `ip`, `host.value` | newest first |
| `dnsRecords` | `recordType`, `value`, `host.value` | newest first |
| `vulnerabilities` | `name`, `severity`, `host.value`, `firstSeen` | newest first |
| `rollups` | `metric`, `key`, `value` | `value` descending |

A default field you are not allowed to read (for example `target.value` without `target.read`) is left out instead of failing the query.


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