Korely
Your Dashboard

Users & agents

List agents

List the agent namespaces written in this key's project, with per-agent active counts plus the tier cap and the slots used across the account, 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 plan's agent cap on the Cloud. 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.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key needs the memories:read scope.

Query parameters

ParameterTypeRequiredDescription
limitintegerOptionalPage size. Defaults to 50. Must be between 1 and 200.
offsetintegerOptionalPagination offset. Defaults to 0. Must be >= 0. At most 9223372036854775807 (2^63-1); a larger one answers 422.

Example request

Terminal window
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
}
FieldTypeDescription
agentsarray<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.
totalintegerAgent 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).
capintegerYour plan's agent cap on the Cloud (hobby 2 / developer 10 / team 100 / scale 500); 0 on Self-hosted, where nothing caps agent names.
usedintegerAgent slots taken across the whole account, counted by name; reconciles with the 429 agent_cap_exceeded error. Larger than total when other projects of the account use names this project does not. Names in imports still queued count too. On Self-hosted, equal to total.

Errors

StatusCodeCause
401invalid_keyMissing or invalid kor_live_ key in the Authorization header.
403forbiddenThe key lacks the memories:read scope.
429quota_exceededMonthly query quota exceeded.
429rate_limit_exceededRate limit exceeded, retry after the Retry-After header.
422invalid_requestlimit 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 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