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

# Paging, limits and cost

> Order and page Attack Surface Query results with cursors, count them with withTotal, and the limits and cost budget each query runs under

## Ordering

`orderBy` takes up to three `{ "field", "dir": "asc" | "desc" }`. Missing values sort last. Ties are broken by `id`, so pages never repeat or skip a row.

Only some fields can be sorted on:

| Resource | Sortable fields |
| - | - |
| `targets` | `value`, `firstSeen` |
| `hosts` | `value`, `firstSeen`, `lastSeen` |
| `services` | `port`, `firstSeen`, `lastSeen` |
| `technologies` | `name`, `firstSeen` |
| `tls` | `notAfter`, `firstSeen` |
| `urls`, `ips`, `dnsRecords` | `firstSeen` |
| `vulnerabilities` | `cvssScore`, `epssScore`, `firstSeen`, `lastSeen` |
| `rollups` | `value` |
| related `http` (e.g. `http.title`) | `title`, `statusCode`, `probedAt` |

Sorting on `firstSeen`, `port`, `notAfter`, a rollup's `value`, and the `lastSeen` of hosts and services is always fast. The others (and any related field) are accepted when the filter keeps the rows to sort small enough; otherwise the query is refused with `COST_EXCEEDED` and a hint to filter or sort by `firstSeen`.

## Paging with cursors

When more rows match than `limit`, the result carries `nextCursor`. Send the **same** query again with that cursor to get the next page:

```json theme={null}
{ "queries": { "urls": { "from": "urls", "select": ["url"], "limit": 100, "cursor": "eyJ2IjoxLCJxIjoi…" } } }
```

* A cursor is bound to its query and workspace: changing the filter, the order or the resource makes it invalid (`INVALID_CURSOR`). `limit` may change between pages.
* A cursor continues after the last row it saw: rows added meanwhile ahead of it are not shown, and nothing is skipped or repeated.
* `nextCursor: null` means this was the last page.

## Totals

`"withTotal": true` adds `total`, the number of rows matching the filter (ignoring the cursor). Counting stops at 10 000: beyond that `total` is `10000` and `totalCapped` is `true`.

A total costs an extra pass over the data. When you only need the number, an aggregate (`"aggregate": { "n": { "fn": "count" } }`) is cheaper.

## Limits

| Limit | API (interactive) | AI agent and MCP | Report mode |
| - | - | - | - |
| Queries per batch | 10 | 5 | 10 |
| Rows per query (`limit`, default 50) | 1 000 | 200 | 50 000 |
| Fields in `select` | 30 | 20 | 30 |
| Includes per query (nested included) | 5 | 3 | 5 |
| Include nesting | 2 levels | 2 levels | 2 levels |
| Rows per include and parent (default) | 50 (10) | 20 (5) | 50 (10) |
| `groupBy` keys / aggregates / `orderBy` keys | 3 / 8 / 3 | 3 / 8 / 3 | 3 / 8 / 3 |
| Conditions per filter (relation tests included) | 50 | 20 | 50 |
| Values per list (`in`, `containsAll`…) | 200 | 50 | 200 |
| Group nesting in a filter | 4 levels | 4 levels | 4 levels |
| Time per database statement | 5 s | 3 s | 120 s |
| Time per batch | 15 s | 8 s | 10 min |
| Response size | 5 MB | 64 KB | 16 MB |
| Longest string returned | 2 000 chars | 512 chars | 2 000 chars |
| Large HTTP fields (`body`, `rawHeader`, `header`) | yes | no | yes |

The request body is limited to 64 KB. A query that hits the response size keeps the rows that fit, sets `truncated: true` and returns a `nextCursor` to continue.

## Cost

Before a query reaches the database, OASM estimates its **cost** from what it asks for: rows × related rows, included rows (which multiply per parent), list filters and relation tests (a `count` more than the others), text searches (`contains`, `startsWith`, `endsWith`) on large text, totals, and a penalty when nothing narrows the query (no window and no exact filter). Each query must stay within the caller's budget:

| Caller | Budget |
| - | - |
| API, interactive | 1 000 |
| AI agent and MCP | 1 000 |
| Report mode | 60 000 |

A full page of any resource over all time, with a total, and an all-time count fit easily. What does not:

* **Include fan-out**: 200 hosts × 20 services each. Lower the limits, or query the child resource directly.
* **Broad text search**: `contains`, `startsWith` or `endsWith` on `value`, `url` or `http.title` over a large page with no other filter.
* **Counting related rows of every row**: a relation `count` over all time. Add a window or an exact filter so fewer parents are counted.
* **Many related fields on a large page.**

Interactive queries then go through the database planner: a query the planner expects to read too much is refused too, even under the static budget. Over budget, the error says by how much and lists **hints** — follow them, or check a query with `POST /api/attack-surface/explain` first. For large exports, use [report mode](https://docs.oasm.io/attack-surface-query/saved-queries-and-reports.md#report-mode).

## Concurrency

Each OASM API instance runs at most three queries at the same time. A query that waits more than two seconds for a slot fails with `BUSY`; retry it.


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