Users & agents

List agents

List the agent namespaces written under this account, with per-agent active counts plus the tier cap and the slots used, so you always know how close you are to the agent cap.

GET /v1/agents

Every distinct agent_id you write under counts as one slot against your tier's agent cap. This endpoint returns those namespaces with their active memory and fact counts, plus cap and used, so a 403 agent_cap_exceeded is never a surprise.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key needs the memories:read 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`.

Example request

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

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<AgentScope>	Page of agent namespaces. Each `AgentScope` has `agent_id`, `memories` (active memory count), `facts` (active fact count), and `last_active` (ISO timestamp, nullable). Fully-forgotten agents still appear with zero counts, they still hold a cap slot.
`total`	integer	Distinct agent namespaces (equal to `used`), the full set length before pagination.
`cap`	integer	Your tier's agent cap (hobby `2` / developer `10` / team `100` / scale `500`).
`used`	integer	Agent slots consumed, reconciles with the `403 agent_cap_exceeded` error.

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`.

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 403 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 (equal to used); page through it with limit and offset. Each call counts against your read query quota.

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.