Users & agents

Audit log

What happened in your project, and what your agents read: one event per call that ran, newest first.

SDK: korely.audit(...), and korely.iter_audit(...) to read every page. The Glossary defines the audit log and the other words used across the docs.

"Who wrote this memory, and what did the agent know when it decided?" Filter by user_id to get the events attributed to one end user: writes, edits, fact writes, corrections and forgets, end-user erasures, reads of one memory, and every read made with that user_id, with the memories and facts it returned. A read made without a user_id, and the event that queues a batch, carry user_id null: find them by target_id or in read. Each memory a batch imports has its own write event (actor worker, meta.batch the job id) with its end user. A read lists ids. To see what the store knew at that moment, read with known_as_of set to the event's ts: Get facts returns the facts as the store knew them then, and Get context the block it could have built. as_of answers another question: what was true then, as the store knows it now.

The log records ids, counts and short labels, never the text of a memory, a fact or a query. Erasing an end user or an agent namespace therefore removes its content for good, and the log still shows that it happened. Forgetting a single memory is recorded as erase too, but keeps the memory and its facts as history. Events are kept for 400 days.

This endpoint returns the events filed under your key's project: every call made with a key, key_create, key_change, a project's create, rename, archive and unarchive (setting_change), a key disconnected by an app (key_revoke), and reads made from the dashboard on this project's data (actor dashboard).

Since 1.0.12, a change made in the dashboard or with an admin key is filed in the project of what it changes (a fact, a key, a webhook or an alias), with that item's end user when it has one. This covers a fact forgotten or corrected, a key revoked, a webhook made, deleted or switched on, a webhook's test delivery, and an alias made or deleted. Opening an event in the dashboard's Audit log to see its memories and facts is a read, and it is filed the same way, in the project and with the end user of each memory and fact it shows. Up to 1.0.11 these were filed under no project (a test delivery was not filed at all), so this endpoint did not return them, and a fact, an alias or the ids an event lists had no end user, so ?user_id= did not find them. A list read in the dashboard is filed with an end user only when the list asked for one: the Memories page of a project with several end users is filed with none, so ?user_id= does not find it.

Events with no project are not returned to a key. Examples: login, logout, the model settings, a webhook for every project, an end user erased in every project, a project deleted, and the reads made in the dashboard with All projects chosen. The dashboard's Audit log lists them under All projects.

For an event made in the dashboard, the log also keeps the name the person signed in with (meta.operator, often an email), and the dashboard's Audit log shows it. Since 1.0.12 this endpoint leaves it out: every key of the project can call this endpoint, so it does not show who signed in to the dashboard.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key needs the memories:read permission (the API calls it a scope). Reading the log does not count against your query quota, and the read is not itself written to the log. It does count against the rate limit.

A key sees only the events of its own account and its own project. A key whose project was deleted falls back to the account's Default project and reads its events.

Query parameters

Example request

curl "https://api.korely.ai/v1/audit?user_id=customer-4812&limit=50" \
  -H "Authorization: Bearer kor_live_..."

from korely_memory import Korely

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

page = korely.audit(user_id="customer-4812", limit=50)

print(page.total)
for e in page.events:
    print(e.ts, e.action, e.target_id, e.read.facts if e.read else None)

import { Korely } from "korely-memory";

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

const { events, total } = await korely.audit({ user_id: "customer-4812", limit: 50 });

console.log(total);
for (const e of events) {
  console.log(e.ts, e.action, e.target_id, e.read?.facts);
}

Response

200 OK. The events, newest first, and how many match. The order is ts descending, then the event's internal id descending, so two events in the same instant keep one order and paging with offset is stable: a page neither repeats nor skips an event that was already there.

{
  "events": [
    {
      "ts": "2026-10-02T09:14:31.218000Z",
      "actor": "rest",
      "action": "read",
      "result": "ok",
      "user_id": "customer-4812",
      "target_id": null,
      "meta": {"endpoint": "context", "memories_read": 3, "facts_read": 2},
      "ip": null,
      "read": {"memories": ["mem_8f2c1a", "mem_41d0e7", "mem_c9a0b2"], "facts": ["fct_a1", "fct_b7"]}
    },
    {
      "ts": "2026-10-02T09:12:05.004000Z",
      "actor": "rest",
      "action": "write",
      "result": "ok",
      "user_id": "customer-4812",
      "target_id": "mem_c9a0b2",
      "meta": {"endpoint": "memories:add"},
      "ip": null,
      "read": null
    }
  ],
  "total": 2
}

Errors

Find the record of an erasure

An end-user erasure (Erase a user) is the event with action erase, user_id the pseudonym, target_id null and meta.endpoint users:delete, with the counts. Filter with action=erase and the original user_id. Deleting one memory (memories:delete) or forgetting one fact (facts:forget) also gives action erase, so read meta.endpoint.

The event does not carry the audit_id that the erasure returned, and no call reads that id back: keep it from the response. The event does not say which key made the call either.