> Source: https://builder.ema.ai/v2/administration/audit-log
> Title: Audit Log

# Audit Log

The audit log is an immutable, workspace-wide record of every meaningful action taken in your workspace: sign-ins, user and role changes, workflow and AI Employee edits, runs, knowledge base changes, integration and API-key events, and more. Use it to investigate unexpected behavior, demonstrate compliance, and hold actions accountable. Events are append-only: nothing in the log can be edited or deleted.

System admins open the full audit log in **Settings → Admin Settings → Governance**, on the **Activity log** tab.

> [INFO]
> **What you can see depends on your role.** Everyone except people with No access sees audit events in the **Activity** feeds on individual screens, such as an AI Employee's **Activity** tab. Each feed shows only the events your role allows (see [Role-based visibility](#role-based-visibility)). The full log and the PII access log are for System admins.

## What an event records

Every event captures who acted, what they did, and what they acted on:

Field

Meaning

`created_at`

When the action happened.

`actor_id`, `actor_name`, `actor_email`

Who performed it, captured at event time.

`actor_role`

The actor's role at the time of the action.

`action`

The action performed (for example `membership.role_updated`, `workflow.published`).

`resource_type`, `resource_id`, `resource_name`

What was acted on. The name is stored at event time.

`resource_version_id`

The version of the resource, when applicable (the basis for change tracking on versioned resources like workflows).

`metadata`

Free-form context about the event (JSON).

`ip_address`

The actor's IP address, when available.

`credential_id`

The integration credential (API key, OAuth client, and so on) that authenticated the call. Absent for a person's session.

`credential_type`

The kind of credential `credential_id` names.

`actor_type`

The kind of principal that acted, such as `system_user` for a system user account.

`end_user_ref`

The partner's own reference to its end user (at most 256 bytes). Opaque to Ema.

`outcome`

How the action ended: `success`, `failure`, or `denied`. Events recorded before this field existed read `success`.

`request_id`

The emitting request's ID, for joining to logs and traces.

Events are emitted asynchronously by every service. The actor and resource names are denormalized into the event at the time it is written, so the log remains accurate even if the user or resource is later renamed or deleted.

## Role-based visibility

Ema filters every audit feed by your role before it loads, so pages, counts and exports include only what you're allowed to see. The table applies to every feed you can open.

Role

What appears in the feed

System admin, User admin, Builder admin (older role)

Every event in the workspace.

Builder

Events on build resources, such as workflows, agents, runs, knowledge bases, documents, integrations, connections, MCP servers, and deployments.

User

Only the events where they were the actor (their own actions).

No access

Nothing.

## Viewing and filtering

The tab shows the most recent events first, loaded in pages with a **Load More** button. You can search and filter the feed using the following controls:

-   **Search activity:** full-text search across event fields.
-   **User:** filter to one or more people who acted.
-   **Resource Type:** for example users, sessions, API keys, workflows, agents, knowledge bases, connections, integrations, or evaluations.
-   **Action:** for example login, logout, user created, role changed, user deactivated, workflow created/published/deleted, run started/completed/failed, agent created, document uploaded, knowledge base created, search executed, connection OAuth connected, integration installed, or API key created/revoked.
-   **Select date:** pick a preset, up to the last 365 days, or set a start and end time. Times are in UTC.

Filters combine, and changing any filter reloads from the first page. To sort the feed, select the **Actor**, **Role**, **Action**, or **Time** column header.

## Contextual activity feeds

The same audit data also appears in context, scoped to a single item. An **Activity** feed shows the audit events for one item: the SSO, Email Domains, and API Keys tabs in Workspace each have one, and most AI Employees have an **Activity** tab. Because each event carries a `resource_version_id`, this is how you track what changed on a versioned resource (such as an AI Employee's workflow), who changed it, and when, in chronological order.

These contextual feeds are powered by the same list endpoint, scoped with `resource_type` and `resource_id`.

## Exporting

Select **Export CSV** to download all events that match your current filters. The export includes, in this column order: Time, Actor Name, Actor Email, Actor Role, Action, Resource Type, Resource Name, Resource ID, Execution Context, Credential ID, Credential Type, Actor Type, End User Ref, Outcome, Request ID. New columns are only ever appended, so a column's position does not change. The file is named `audit-log-<date>.csv`. Your search terms, date range, and other filters apply to the export, so the file holds every event that matches them, not only the rows loaded on screen. One export holds up to 100,000 events.

## PII access log

When [PII governance](/builder/v2/administration/pii-and-governance) is enabled, every PII decision is recorded as a dedicated audit event (`pii_access` or `pii_data_export`). A separate, `system_admin`\-only endpoint, `GET /audit/pii-access`, projects these events into compliance-friendly fields rather than requiring you to parse raw metadata:

Field

Meaning

`entity_type`

The taxonomy entity the decision was made for (for example `EMAIL_ADDRESS`).

`decision`

What happened to the value: `Tokenize`, `PartialMask`, `Redact`, or `PassThrough`.

`boundary`

Where the decision applied: for example `LLM_COMPLETION`, `CHAT_DISPLAY`, or `TENANT_EXPORT`.

`purpose_category`

The purpose recorded with the decision (for example `END_USER_AUTHORED`, `INTEGRATION_EGRESS`).

`integration_type`

The downstream integration or LLM vendor, on egress decisions.

`byte_count`

Bytes exported, on `pii_data_export` events.

This endpoint accepts filters for time range, actor, entity type, boundary, purpose, integration type, and decision, so you can answer questions like "what cleartext PII left the workspace for which integration, and when."

## Reference: endpoints

Action

Endpoint

Access

List audit events (role-filtered)

`GET /events`

Role-based visibility

Get one event

`GET /events/{id}`

Role-based visibility

List PII-access events

`GET /audit/pii-access`

`system_admin`

The event feed uses cursor pagination (`limit` up to 200, defaulting to 50) and supports `actor_id`, `resource_type`, `resource_id`, `action`, `group_id`, `from`, `to`, `credential_id`, `end_user_ref`, and `outcome` filters.

`credential_id`, `end_user_ref`, and `outcome` are validated strictly: a malformed value returns `422 VALIDATION_ERROR` with a `details` array whose `field` names the parameter. They never silently widen to all events.

Parameter

Type

Behavior

`credential_id`

UUID

Returns only events made with this integration credential. A non-UUID value is a 422 error.

`end_user_ref`

string

Exact, case-sensitive match against the partner end-user reference. At most 256 bytes; a longer value is a 422 error.

`outcome`

comma-separated string

Returns events matching any of the listed outcomes. Each value must be `success`, `failure`, or `denied` (exact case). Example: `outcome=failure,denied`. Any other value is a 422 error.

> [INFO]
> **Retention.** Audit events are kept for 365 days by default. Ema sets this window; it isn't a setting in the app. Cleanup is a background process; there is no API that edits or deletes individual events. The purge is skipped for any workspace under a legal hold. If the legal-hold check cannot be completed, the purge is also skipped for that workspace (fail-safe behavior) until the check succeeds on the next sweep.

## What's next

-   [Governance and permissions](/builder/v2/administration/governance-and-permissions): how role determines audit visibility.
-   [PII and data governance](/builder/v2/administration/pii-and-governance): the policy decisions the PII access log records.
-   [User management](/builder/v2/administration/user-management): the source of user, role, and membership events.
