insights operations

The exact fields each insights.* operation takes and returns.

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 its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.

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.