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:
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 thanlimit, the result carries nextCursor. Send the same query again with that cursor to get the next page:
- A cursor is bound to its query and workspace: changing the filter, the order or the resource makes it invalid (
INVALID_CURSOR).limitmay 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: nullmeans 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
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 (acount 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:
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,startsWithorendsWithonvalue,urlorhttp.titleover a large page with no other filter. - Counting related rows of every row: a relation
countover all time. Add a window or an exact filter so fewer parents are counted. - Many related fields on a large page.
POST /api/attack-surface/explain first. For large exports, use 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 withBUSY; retry it.