---
title: search operations
---

The exact fields each `search.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/pt-BR/reference/http-api#request) its namespace and agent; see [identities and namespaces](/pt-BR/concepts/identities-and-namespaces). The [operations index](/pt-BR/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `search.query`

Search every plane of the caller's Loom content in one call.

`POST /v1/search.query` · MCP `loom_search` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `query` | `str` | required | The question, searched in every plane at once. |
| `top_k` | `int` | `5` | At most this many hits per section (1-100); tracker search caps it at 50, duplicate checks at 10. |
| `tags` | `list[str]` | *(computed)* | Tag filter for the memory and knowledge legs; profile and conversations ignore it. |
| `namespace_scope` | `Literal['this', 'all_mine']` | `'all_mine'` | Memory, knowledge, profile and conversation scope: `this` reads the addressed namespace; `all_mine` (default) adds readable memory-kind namespaces. |
| `recipe` | `Literal['', 'fast', 'balanced', 'quality', 'verbatim', 'code', 'temporal', 'graph']` | `''` | Named `memory.search` preset for the memory leg (`fast`, `balanced`, `quality`, ...); empty = the server's defaults. |
| `bodies` | `Literal['full', 'excerpt', 'none', 'unit']` | `'excerpt'` | What each memory hit carries: `excerpt` (the first 200 characters; a decision or a constraint as stored), `full` (the stored clip), `none` (keys and scores only) or `unit` (whole values within a budget). |
| `explain` | `bool` | `False` | Every section unwithheld, and the ranking terms of each memory hit. |
| `live` | `bool` | `False` | Search the asker's connected sources without storing their results; off by default. |
| `page` | `str` | `''` | A `memory.next_page` handle from an earlier answer, to read the memory leg's next page; empty = the first page. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `tracker` | `dict[str, Any] \| None` | Cited issue/PR matches, or a duplicate-check verdict for a scoped defect report even with no matches; absent for empty general search or an unavailable, failed or timed-out tracker leg. |
| `live` | `LiveSearchResults \| None` | Ephemeral connected-source hits; absent unless the optional live leg answered. |
| `memory` | `dict[str, Any]` | The `memory.search` result plus the scoped repository's decisions, rendered as a reader block, without the hits the calibration flagged below its threshold (unless every hit is flagged). |
| `knowledge` | `dict[str, Any]` | The `knowledge.search` result plus the scoped repository's documents, hits below the knowledge similarity floor dropped. |
| `profile` | `dict[str, Any]` | Profile sections whose label or text matches the query words, then by meaning. |
| `conversations` | `dict[str, Any]` | The `conversation.search` hits under `results`. |
| `withheld` | `dict[str, Any] \| None` | Counts of hits held back per section by the answer-first rules, with `reason`; absent when nothing was withheld or `explain` is set. |
| `namespaces_skipped` | `list[str]` | The caller's namespaces no leg read because the fan-out stops at `memory_search_fanout_max_namespaces`; address one by name to search it. |

<!-- prettier-ignore-end -->
