---
title: agents operations
---

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

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

## `agents.connected`

The agents active in a window: last seen, operations and cost per agent.

`POST /v1/agents.connected` · MCP `loom_agents_connected` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str \| None` | `None` | Empty → org-wide rollup across every namespace the caller can see. |
| `window_hours` | `int` | `24` | How far back to look. 24h is the right default for the "did my restart take effect" check; bump up for trend-style inspection. |
| `count_only` | `bool` | `False` | The sidebar's badge wants one number — how many agents were first seen inside the window and did something — not every agent's row. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[ConnectedAgent]` | One row per agent seen in the window, most recently seen first; empty with `count_only` or when the caller can read no namespace in the org. |
| `window_hours` | `int` | The lookback the rows cover, in hours (echoes the request). |
| `new_count` | `int \| None` | With `count_only`, the number of agents first seen inside the window with at least one op; None otherwise. |

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