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.

GET /v1/users

SDK: korely.users(...). Each end user you write for (with a user_id) shows up here once it has at least one active memory or fact. Use it to render a list of your customers, to see whose data Korely holds, or to drive a per-user dashboard.

Do not use it as the list of people to erase. It leaves out an end user who has no active memory or fact left, and it returns one page at a time. 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.
`users[].facts`	integer	Active facts of this end user: the ones true now.
`users[].last_active`	string	ISO 8601 time at which the newest active memory or fact of this end user was created.
`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.