---
title: "List agents in organization"
method: GET
path: "/orgs/{org_id}/agents"
tags: ["Organizations"]
---

# List agents in organization

`GET /orgs/{org_id}/agents`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/orgs/{org_id}/agents`
- Auth: HTTP bearer

## Path parameters

- `org_id` string, required

## Query parameters

- `mine` boolean
- `limit` integer
- `offset` integer
- `groupId` string

## Response `200`

Organization agents. Includes total/limit/offset only when limit or offset was supplied.

- object
  - `agents` Agent[], required
    - `id` string
    - `claimed` boolean: Public projection only: whether the agent has been claimed by a user.
    - `avatar_url` string, nullable
    - `claimed_by` string, nullable: Owner projection: user id that claimed the agent.
    - `created_by` string, nullable: Owner projection: user id that created the agent (provenance).
    - `org_id` string, nullable: Owner projection: the agent's org binding (ADR-062 authz boundary).
    - `agent_proof_hash` string, nullable: Owner projection: captured hash_proof of the bound key (mig 263).
    - `agent_proof_captured_at` string, date-time, nullable
    - `deleted_at` string, date-time, nullable: Owner projection: soft-delete timestamp (null when live).
    - `agent_hash` string: First 16 hex chars of `SHA256(apiKey + '|' + agentName)` for named agents, or `SHA256(apiKey)` for unnamed singleton agents. The gateway computes the same value on each request and uses it as the lookup key. See [Agent Identity](https://docs.mnemom.ai/concepts/agent-identity#agent_hash--the-canonical-identity-hash).
    - `user_id` string, nullable
    - `email` string, nullable
    - `claimed_at` string, date-time, nullable
    - `last_seen` string, date-time, nullable
    - `name` string, nullable: Agent name (2-32 chars, alphanumeric + hyphens). Present on all list and get responses.
    - `containment_status` 'active' | 'paused' | 'killed', nullable: Containment state of the agent (ADR-053).
    - `key_prefix` string, nullable: First 8 chars of the bound API key hash — useful for key-rotation debugging.
    - `status` 'active' | 'offline'
    - `caller` 'anonymous' | 'authenticated' | 'org_member': Self-describing caller context for THIS response. `org_member` callers receive the full owner record (all fields here); `anonymous`/`authenticated` (non-member) callers receive the reduced public projection (id, name, claimed, created_at, last_seen, status, avatar_url, caller). The differing field set is GOVERNED by this value — read it instead of inferring why a field is absent.
    - `public` boolean: Identity-record visibility axis — whether the agent's IDENTITY RECORD is publicly discoverable. This is DISTINCT from reputation visibility: every registered agent's reputation is public by accountability standard (see `ReputationScore.visibility`). `public` here governs only the identity record, never the Trust Rating.
    - `aip_enforcement_mode` 'observe' | 'enforce' | 'nudge', nullable
    - `billing_account_id` string, nullable
    - `created_at` string, date-time
    - `groups` object[]: Active groups this agent belongs to, name-ordered; `[]` when none. Present on org-fleet rows (GET /v1/orgs/{org_id}/agents). Archived groups are excluded.
      - `id` string, required
      - `name` string, required
      - `color` string, nullable, required: Group color (hex, e.g. `#0d9488`); `null` when unset.
  - `total` integer: Total agents before pagination (present only when paginating).
  - `limit` integer: Echoed page size (paginated only).
  - `offset` integer: Echoed offset (paginated only).

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.
- `503`: The fleet read could not be served. `error.code` is `fleet_stats_unavailable` while the org fleet summary is still being built (refresh pending): no fleet list or export is produced, so an empty result is never returned in its place. Retry after `Retry-After` seconds (`error.details.retry_after_seconds`; `error.details.retryable` is `true`). Other 503s on this route mean an upstream dependency is unavailable.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/274b7a6ea182?raw)