---
title: "List Agents"
method: GET
path: "/v1/agents"
tags: ["v1"]
---

# List Agents

`GET /v1/agents`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/agents`
- Auth: HTTP bearer

List the agent namespaces this developer has written under (the distinct
non-null ``agent_id`` values), each with its active memory + fact counts and
last-active time, plus ``cap``, the most agent names a write may bring in
(0 when nothing caps them, as on an install of one's own), and ``used``,
how many of them the cap counts.

The namespace set counts memories AND direct fact writes, including
soft-deleted / invalidated rows; the per-agent ``memories``/``facts`` counts
reflect only active items, so an agent whose data was all forgotten still
appears, with zero counts, until ``DELETE /v1/agents/{agent_id}`` purges it.
The default (null) namespace is never counted, and omitted.

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- AgentsResponse
  - `agents` AgentScope[], required
    - `agent_id` string, required
    - `memories` integer, required
    - `facts` integer, required
    - `last_active` string, nullable, required
  - `total` integer, required
  - `cap` integer, required: The most agent names a write may bring in: 0 when nothing caps them, as on an install of one's own. A write under a new name past it is refused.
  - `used` integer, required: The agent names `cap` counts, over the set it caps (the whole account where a plan caps them); with no ceiling, the names this key sees, which `total` counts.

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry.

---

[API](https://skmtc.dev/korely/apis/korely-agents-api.md) · [All operations](https://skmtc.dev/korely/apis/korely-agents-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korely/apis/korely-agents-api/revisions/8a40bf09eca1?raw)