Skip to content

Audit Trail

Every change in the organization is recorded: who did what, to what, and when. Sign-ins (including refused ones), edits to boards and records, Document Model changes, user and role changes, API keys, SSO settings, workflows and more.

The SDK exposes two namespaces:

  • client.auditLogs / client.audit_logs — the live log: read, filter, count, export everything, undo a change
  • client.auditArchives / client.audit_archives — older months kept as files: download them, bring them back, set how long the log is kept

The organization needs the Audit Trail feature. Initialize the client first (see Installation or Quick Start).


Read the log

const page = await client.auditLogs.list({
resource: ["user", "role"], // one value or several
action: ["create", "update", "delete"],
from: "2026-11-01",
limit: 50,
});
for (const e of page.data) {
console.log(e.createdAt, e.actor.email, e.action, e.resource, e.resourceName);
}

Each entry has id, action, resource, resourceId, resourceName, actor (userId, name, email), summary, changes (before and after), metadata, revertable and createdAt. client.auditLogs.get(id) reads one entry.

Filters

FilterMeaning
userId, resource, resourceId, action, boardIdOne value or several
categoryIdEvery board in this category (ignored when boardId is given)
runIdWhat one workflow or agent run did
caseIdWhat one AI case did
from, toISO dates
qText search
importsonly or exclude the entries an import made
includeArchiveAlso read archived months (slower; archived entries cannot be undone)
limit, page, cursorPaging: limit up to 100 (default 25); cursor is pagination.nextCursor of the previous page

action is one of create, update, delete, upload, login, login_failed (a refused sign-in; metadata.reason says why), revert, export, download, connect.

Common resource values:

AreaValues
Data boards and Knowledge Hubboard, board_item, file, folder, integration
DocIQ and board configurationdoc_schema, doc_category, doc_settings, dociq_extraction, segmentation, scheduler, automation
People and accessuser, team, team_user, role, api_key, sso_config, oidc_role_mapping, business_unit, organization, session
AI, apps and workflowsassistant, llm_provider, flow, tool_server, use_case, app_install
Channelschannel, contact, campaign, message_template
The audit log itselfaudit_retention

Export everything

iterate() walks every matching entry, page by page, newest first.

import { createWriteStream } from "node:fs";
const out = createWriteStream("audit-2026-10.jsonl");
for await (const e of client.auditLogs.iterate({ from: "2026-10-01", to: "2026-10-31T23:59:59Z" })) {
out.write(JSON.stringify(e) + "\n");
}
out.end();

Count

summary() takes the same filters and returns total, imports, byAction, byResource and byUser.

const s = await client.auditLogs.summary({ from: "2026-11-01", action: "login_failed" });

Undo a change

An entry with revertable: true can be undone. The undo is itself recorded as a revert entry. It needs the audit_trail:write permission.

const { revertEntry } = await client.auditLogs.revert(entryId);

Archived months

The live log keeps the most recent months (hotMonths, for example 3). Older months are moved to files, one per month, each with a SHA-256 hash that also names the previous month’s hash, so the months form a chain.

List and download

import { createHash } from "node:crypto";
import { gunzipSync } from "node:zlib";
const { hotFrom, archives } = await client.auditArchives.list();
const month = archives.find(a => a.status === "archived")!;
const file = await client.auditArchives.download(month.month); // { data, filename, sha256, filtered }
const ok = createHash("sha256").update(Buffer.from(file.data)).digest("hex") === file.sha256;
const entries = gunzipSync(Buffer.from(file.data)).toString("utf8").trim().split("\n").map(l => JSON.parse(l));

A file is gzip-compressed JSON Lines, one entry per line. Pass resource (e.g. ["user", "role"]) to download only those entry types; filtered is then true and sha256 is the hash of what was sent.

An archive’s status is archived, restoring, restored (back in the live log until restoreExpiresAt), failed or purged (deleted at the end of the retention).

Bring a month back

restore() copies archived months back into the live log, so auditLogs.list() reads them again. It runs in the background: the months show restoring, then restored. list().restore gives the limits (default and maximum days, maximum months per restore).

const { months, expiresAt } = await client.auditArchives.restore({ from: "2026-05", to: "2026-06" });
await client.auditArchives.extend("2026-05", 7); // keep it 7 days longer
await client.auditArchives.release("2026-05"); // send it back before it expires

Retention

How long the log is kept, in total months (live and archived).

const retention = await client.auditArchives.getPolicy(); // { totalMonths, hotMonths, minTotalMonths, maxTotalMonths, pending, canEdit, … }
const { outcome } = await client.auditArchives.setPolicy({ totalMonths: 24 });

A longer retention applies at once (outcome: "increased"). A shorter one is scheduled after a grace period (outcome: "scheduled", see retention.pending) and can be called off with cancelPendingPolicy(). A legal hold, which stops all deletion, is placed or lifted by iMBrace only.

Who can do what

ActionWho
Read the log, list archives, read the retentionMembers with access to the audit log
Undo a changeaudit_trail:write permission
Download, restore, extend, releaseAdmins
Change the retentionThe organization’s owner or an admin

Refusals come back as errors with a code, for example live_month (409: that month is still live), not_archived (404), purged (410), not_restored (409).


See also