Skip to main content

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 than limit, 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). 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

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

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.