---
title: insights operations
---

The exact fields each `insights.*` 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](/docs/reference/http-api#request) its namespace and agent; see [identities and namespaces](/docs/concepts/identities-and-namespaces). The [operations index](/docs/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

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

## `insights.catalog`

List the tables `insights.query` can read: each column with its type and meaning, how to read the table correctly (one live row per key, or one row per event), and the caps a statement runs under.

`POST /v1/insights.catalog` · MCP `loom_insights_catalog` · role `viewer` · read · not listed under the MCP `all` toolset

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

| Output field | Type | Meaning |
| --- | --- | --- |
| `tables` | `list[CatalogTable]` | The tables insights.query reads, with their columns and how to read them. |
| `max_result_rows` | `int` | The most rows one statement returns; past it the answer is truncated. |
| `max_execution_s` | `float` | The longest one statement runs before ClickHouse stops it (this replica's cap; during a roll the stored caps profile may differ). |
| `max_rows_to_read` | `int` | The most rows one statement may read; add a time or key filter past it. |

## `insights.query`

Run one read-only SQL SELECT (or WITH) over the tables `insights.catalog` lists, for questions no other read answers: counts, rankings and trends over memories, conflicts, usage, documents and the…

`POST /v1/insights.query` · MCP `loom_insights_query` · role `viewer` · read · not listed under the MCP `all` toolset

| 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. |
| `sql` | `str` | required | One SELECT or WITH statement over the tables insights.catalog lists; it reads only this namespace's rows. |
| `limit` | `int` | `100` | Rows to return at most (default 100); the deployment's cap (LOOM_CH_ANALYSIS_MAX_RESULT_ROWS) wins when lower. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `columns` | `list[AnalysisColumn]` | The statement's result columns, each with its ClickHouse type. |
| `rows` | `list[list[Any]]` | One list per row, in `columns` order; dates, UUIDs and decimals as strings. |
| `row_count` | `int` | How many rows `rows` holds, at most `limit`. |
| `truncated` | `bool` | More rows matched than `limit`; narrow the statement or aggregate. |
| `sql_digest` | `str` | The digest the request ledger records for `sql` (`sha256:<hex>/<length>`), which a citation of the statement is checked against. |

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