Users & agents

List users

List your distinct end-user namespaces, each with its active memory count, active fact count, and last-active time, sorted most-recently-active first.

GET /v1/users

SDK: korely.users(...). Each end user you scope a write to (the user_id namespace) shows up here once it has at least one active memory or fact. Use it to render an account list, audit who Korely is remembering, or drive a per-user dashboard.

Authentication

HTTP header, required: Authorization: Bearer kor_live_....

Query parameters

Parameter	Type	Required	Description
`agent_id`	string	Optional	Filter to one agent namespace. Defaults to none (all agents). When set, both the memory and fact aggregates are restricted to that `agent_id`.
`limit`	integer	Optional	Page size. Default `50`, between `1` and `200`.
`offset`	integer	Optional	Pagination offset. Default `0`, must be `>= 0`.

Example request

curl "https://api.korely.ai/v1/users?agent_id=support-bot&limit=50&offset=0" \
  -H "Authorization: Bearer kor_live_..."

from korely_memory import Korely

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

page = korely.users(
    agent_id="support-bot",
    limit=50,
    offset=0,
)

print(page.total)            # 2
for user in page.users:
    print(user.user_id, user.memories, user.facts, user.last_active)

import { Korely } from "korely-memory";

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

const page = await korely.users({
  agent_id: "support-bot",
  limit: 50,
  offset: 0,
});

console.log(page.total); // 2
for (const user of page.users) {
  console.log(user.user_id, user.memories, user.facts, user.last_active);
}

Response

200 OK. A page of end-user namespaces, plus the total count of distinct end users across the full aggregated set.

{
  "users": [
    {
      "user_id": "customer-giulia-4812",
      "memories": 14,
      "facts": 31,
      "last_active": "2026-03-02T11:02:10+00:00"
    },
    {
      "user_id": "customer-marco-2207",
      "memories": 3,
      "facts": 5,
      "last_active": "2026-02-18T08:40:00+00:00"
    }
  ],
  "total": 2
}

Field	Type	Description
`users`	array<UserScope>	The page of end users. Each `UserScope` has `user_id` (the end-user namespace), `memories` (active memory count), `facts` (active fact count), and `last_active` (ISO 8601 timestamp, nullable).
`total`	integer	Total distinct end users, the length of the full aggregated set, before pagination is applied.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `kor_live_` key, `Authorization` header absent or unverifiable.
`403`	`forbidden`	The key lacks the `memories:read` scope required to read user namespaces.
`429`	`quota_exceeded`	Monthly query quota exceeded. Resets at the next billing cycle, or upgrade.
`429`	`rate_limit_exceeded`	Per-key rate limit exceeded. Honor the `Retry-After` header and back off.
`422`	`invalid_request`	`limit` is outside `1..200`, or `offset` is below `0`.

Notes

Memory-only and fact-only users both appear. The counts aggregate active memories (deleted_at IS NULL) and direct fact writes (invalid_at IS NULL), so an end user that only has facts still shows up.
The default namespace is omitted. Writes made without a user_id (the null end-user namespace) are not listed here.
Sort order. Most-recently-active first; users with no timestamp (last_active: null) sort last.
Pagination. The page is sliced after aggregation (users[offset:offset+limit]); total always reflects the full set length, independent of limit and offset.
Counts as a read. Each call draws from your monthly query quota.

List agents, your distinct agent_id namespaces.
Forget a user, delete everything Korely remembers for one end user.
SDK reference, the typed client used in the examples above.