Users & agents

List users

List the end users in the key's project, each with its count of active memories, its count of active facts and the time of its latest activity, most recent first. Since 1.0.23 an end user with nothing live is listed too, with zero counts.

GET /v1/users

SDK: korely.users(...). Each end user you write for (with a user_id) shows up here as soon as Korely holds anything of theirs, and stays until you erase them: a memory or fact, one that is forgotten or closed, a name you declared for them, the reads of a named reader, or what was learned of them. The counts and last_active still count what is live only, so an end user whose memories are all forgotten shows 0, 0 and null. Up to 1.0.22 such an end user was left out, although erasing the end user took their data too. Use it to render a list of your customers, to see whose data Korely holds, or to drive a per-user dashboard.

A script that read the list as "the active end users" keeps those whose memories or facts is above zero. The list is what an erasure would find, but a batch that is not imported yet is not read for it (its end users appear once the job imports them; erasing an end user takes a queued batch's items too), and it returns one page at a time, so keep the ids you wrote and erase from those (Erase a user).

The Glossary defines the words used across the docs.

Authentication

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

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`. At most `9223372036854775807` (2^63-1); a larger one answers `422`.

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	The page of end users, one object per end user with the four fields below.
`users[].user_id`	string	The end user's id, exactly as you wrote it.
`users[].memories`	integer	Active memories of this end user: the ones not forgotten. `0` when none is live.
`users[].facts`	integer	Active facts of this end user: the ones true now.
`users[].last_active`	string · null	ISO 8601 time at which the newest active memory or fact of this end user was created. `null` when nothing of theirs is live.
`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.
`429`	`quota_exceeded`	Monthly query quota exceeded. Resets on the 1st of the month (UTC), or upgrade.
`429`	`rate_limit_exceeded`	The account's request ceiling (on the Cloud, the plan's minute, hour or day window), shared by every key of the account. Retry after the `Retry-After` header.
`422`	`invalid_request`	`limit` is outside `1..200`, `offset` is below `0` or above the maximum, or `agent_id` is over 255 characters or holds a NUL byte.
`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

Memory-only and fact-only users both appear. The counts aggregate active memories (not forgotten) and facts true now, extracted or written directly (a fact closed on a future date still counts; one valid from a future date does not yet), 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. Newest last_active first. Two end users with the same time go by id, so a page never repeats or skips one.
A confined key sees only its own end users. The list and total cover the end users the key is confined to.
Pagination. Users are ordered by last activity, most recent first, and the page is cut with limit and offset; total is the number of end users that match the request (after the agent_id filter, if you pass one), independent of limit and offset.
Counts as a read. Each call draws from your monthly query quota.

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