Users & agents

List agents

List the agent namespaces written in this key's project, with each one's active counts, plus your plan's agent cap and the slots used across the account, so you know how close you are to the cap.

GET /v1/agents

SDK: korely.list_agents(). Every distinct agent_id you write under counts as one slot in its project against your plan's agent cap on the Cloud: the same name in two projects is two slots. This endpoint returns those namespaces with their active memory and fact counts, plus cap and used, so a 429 agent_cap_exceeded is never a surprise. The Glossary defines the words used across the docs.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key needs the memories:read permission (the API calls it a scope).

Query parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Page size. Defaults to `50`. Must be between `1` and `200`.
`offset`	integer	Optional	Pagination offset. Defaults to `0`. Must be `>= 0`. At most `9223372036854775807` (2^63-1); a larger one answers `422`.

Example request

curl "https://api.korely.ai/v1/agents?limit=50" \
  -H "Authorization: Bearer kor_live_..."

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

page = korely.list_agents(limit=50)

print(page.used, "of", page.cap, "agent slots used")
for agent in page.agents:
    print(agent.agent_id, agent.memories, agent.facts, agent.last_active)

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

const page = await korely.listAgents({ limit: 50 });

console.log(page.used, "of", page.cap, "agent slots used");
for (const agent of page.agents) {
  console.log(agent.agent_id, agent.memories, agent.facts, agent.last_active);
}

Response

200 OK. A page of agent namespaces with active counts, plus the tier cap and the slots used.

{
  "agents": [
    {
      "agent_id": "onboarding-bot",
      "memories": 12,
      "facts": 27,
      "last_active": "2026-03-02T11:02:10+00:00"
    },
    {
      "agent_id": "support-triage",
      "memories": 0,
      "facts": 0,
      "last_active": null
    }
  ],
  "total": 2,
  "cap": 2,
  "used": 2
}

Field	Type	Description
`agents`	array	Page of agent namespaces, one object per agent with the four fields below. An agent whose data is all forgotten still appears, with zero counts, because it still holds a cap slot.
`agents[].agent_id`	string	The agent namespace, exactly as you wrote it.
`agents[].memories`	integer	Active memories under this agent: the ones not forgotten.
`agents[].facts`	integer	Active facts under this agent: the ones true now.
`agents[].last_active`	string · null	ISO 8601 time at which the newest active memory or fact of this agent was created. `null` when it has none; those agents come last.
`total`	integer	Agent namespaces in this key's project, before pagination (for a key confined to some end users, those found in its end users' rows; such a key cannot delete an agent namespace).
`cap`	integer	Your plan's agent cap on the Cloud (hobby `2` / developer `10` / team `100` / scale `500`); `0` on Self-hosted, where nothing caps agent names.
`used`	integer	Agent slots taken across the whole account, one per project and name; reconciles with the `429 agent_cap_exceeded` error. Larger than `total` when other projects of the account hold agents: a key reads how many agents the account holds, never which. Names in imports still queued count too. On Self-hosted, equal to `total`.

 Errors
  Status Code Cause
  401 invalid_key Missing or invalid kor_live_ key in the Authorization header.
 403 forbidden The key lacks the memories:read scope.
 429 quota_exceeded Monthly query quota exceeded.
 429 rate_limit_exceeded Rate limit exceeded, retry after the Retry-After header.
 422 invalid_request limit is outside 1..200, or offset is below 0 or above the maximum.
 503 unavailable The key could not be checked because the database did not answer, or the request waited past one of the store's deadlines. Retry after the seconds in Retry-After.
 
 
 Notes
  Used reconciles with the cap. The cap-defining set counts any row carrying the agent_id, including soft-deleted and invalidated rows, so used always matches the 429 agent_cap_exceeded error. The per-agent memories and facts counts reflect only active rows.
 Forgotten agents still hold a slot. An agent you've fully forgotten surfaces with zero counts but keeps its cap slot, reuse the agent_id or pick a fresh one, knowing it counts.
 The default namespace is never counted. Memories written without an agent_id are omitted from this list and don't consume a slot.
 Pagination. total is the full set length of this project; page through it with limit and offset. Each call counts against your read query quota.
 
 Related
  Delete an agent, free a slot by purging a namespace.
 List users, the end users you've written memories for.
 Add a memory, write under an agent_id to create a namespace.
 SDK reference, the typed client surface.

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `kor_live_` key in the `Authorization` header.
`403`	`forbidden`	The key lacks the `memories:read` scope.
`429`	`quota_exceeded`	Monthly query quota exceeded.
`429`	`rate_limit_exceeded`	Rate limit exceeded, retry after the `Retry-After` header.
`422`	`invalid_request`	`limit` is outside `1..200`, or `offset` is below `0` or above the maximum.
`503`	`unavailable`	The key could not be checked because the database did not answer, or the request waited past one of the store's deadlines. Retry after the seconds in `Retry-After`.