1. Builder Docs
  2. Administration
  3. Audit Log

AIE Audit Log (Change Log)

The AIE Audit Log tracks every significant change made to an AI Employee, providing a chronological record of who changed what and when. Use the audit log to troubleshoot unexpected behavior, satisfy compliance requirements, and maintain accountability across your team.

What Gets Logged

The audit log captures changes across the AI Employee lifecycle:

CategoryExample Events
Workflow changesWorkflow canvas edits, node additions/removals, connection changes
Configuration updatesAI Employee settings changes, integration configuration changes, model parameter adjustments
Persona modificationsName changes, status changes (enabled/disabled), description updates
Import operationsAI Employee import started, completed, or failed (see Export & Import)

Each log entry contains:

  • Event type -- The specific action performed.
  • Event category -- The broad category (workflow, configuration, persona, etc.).
  • Summary -- A human-readable description of the change.
  • Details -- Structured data with the specifics of the change (JSON format).
  • Actor -- The user who performed the action (null for system-initiated events).
  • Timestamp -- When the event occurred.
  • Reference ID -- An optional link to a related entity (e.g., workflow ID, import request ID).

Viewing the Audit Log

Access Requirements

Viewing the audit log requires the CAN_VIEW_PERSONA permission. At the Workspace level, this means:

  • Workspace Admin can view audit logs for all AI Employees.
  • AI Employee Admin and AI Employee Manager can view audit logs for their specific AI Employee.

Tenant isolation is enforced -- you can only view audit logs for AI Employees within your own tenant.

API Access

The audit log is available through two interfaces:

InterfaceEndpointFormat
REST (OTEL format)GET /personas/{persona_id}/changelog/otelOpenTelemetry log records with attributes
gRPCListPersonaAuditLogProtobuf PersonaAuditEntry messages

REST (OTEL) Endpoint

The REST endpoint returns audit log entries formatted as OpenTelemetry log records, making it compatible with observability pipelines.

Request parameters:

ParameterTypeDefaultDescription
limitinteger100Number of entries to return (1--1000).
page_tokenstringnullCursor for the next page of results.

Response fields:

  • log_records -- Array of OTEL log records, each containing time_unix_nano, body.string_value (the summary), and attributes (event type, category, actor, details).
  • next_page_token -- Pass this value as page_token in the next request to fetch the next page. Empty string when no more pages exist.

gRPC Endpoint

The ListPersonaAuditLog RPC returns strongly-typed PersonaAuditEntry messages.

Request fields:

FieldTypeDescription
persona_idstringThe AI Employee ID to query.
page_sizeint32Entries per page (default 20, max 1000).
page_tokenstringCursor for pagination.

Pagination

The audit log uses cursor-based pagination. Each response includes a next_page_token (base64-encoded). Pass this token in the subsequent request to retrieve the next page. When the token is empty, you have reached the end of the log.

Entries are always returned in reverse chronological order (newest first).

Recording Events

Audit events are recorded automatically by the platform when changes occur. External services can also record events via the RecordPersonaAuditEvent gRPC endpoint. Required fields for recording:

  • persona_id -- The AI Employee being modified.
  • tenant_id -- Must match the authenticated user's tenant.
  • event_type -- The action type.
  • event_category -- The category of the change.
  • summary -- Human-readable summary.

Optional fields include details (structured JSON data), actor_user_id, and reference_id.

Last updated: Jul 3, 2026