---
title: "List agent groups in an organization"
method: GET
path: "/agent-groups"
tags: ["Agent Groups"]
---

# List agent groups in an organization

`GET /agent-groups`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/agent-groups`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Mnemom-Api-Key`

List the active agent groups for an organization. With no `q`, groups are returned ordered by creation time (newest first). With `q`, groups are filtered by a case-insensitive name search and ranked most-relevant-first (exact → prefix → fuzzy, then recency, then member count) so a suggestion UI can offer existing groups. Each item carries a `match_type` discriminator (`none` when no `q` was supplied). Optional `limit`/`offset` bound the response; when neither is supplied the legacy `{ groups }` envelope is returned unchanged. Returns an empty array when nothing matches.

## Query parameters

- `org_id` string, required
- `q` string
- `limit` integer
- `offset` integer

## Response `200`

List of active groups (filtered + ranked when `q` is supplied)

- object
  - `groups` object[], required
    - `color` string, nullable: Group colour as #rrggbb, or null when no colour is set.
    - `match_type` 'exact' | 'prefix' | 'fuzzy' | 'none': How this group matched `q` (`none` when no `q` was supplied).
  - `total` integer: Total matched groups before paging (present only when paginated).
  - `limit` integer: Applied page size (present only when paginated).
  - `offset` integer: Applied row offset (present only when paginated).

## 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`: An upstream dependency is currently unavailable. The request was not processed; retry after the cooldown window.

---

[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)