Audit logging - Braintrust

The Audit log records administrative actions in your Braintrust organization, such as creating projects, changing settings, granting permissions, managing members, and creating API keys. Reads of your data can also be logged as an optional add-on.

only available on the Enterprise plan.

Audit logs are only recorded while your organization is on an Enterprise plan. If you upgrade from Pro to Enterprise, audit logs are recorded from the time of the upgrade.

Self-hosted deployments require data plane v2.6.0 or later for audit logging. On earlier versions, administrative events are recorded but aren’t queryable.

Grant access

Members of the Owners permission group can read organization audit logs by default. To let anyone else read them, grant the organization-level Read audit logs permission in Settings > Permission groups.

The Read audit logs permission grants read access to audit log entries for the organization. It does not grant access to modify the audited resources.

View the audit log

To view recent organization activity, go to Settings > Audit log. The table lists actions performed by members of your organization, with the most recent events first. Use the controls above the table to customize the view:

Time range: Select Last 24 hours, Last 7 days, or Last 30 days. The default is Last 7 days.
Filters: Narrow results by fields such as actor, event type, or resource.
Columns: Show or hide columns. ID, details, and before and after change columns are hidden by default.

To run more complex queries or download results, select Open SQL sandbox. See Audit data reads and modifications and the SQL reference for query details.

Query the audit log

Users with the Read audit logs permission can query audit logs with SQL using the audit_logs() data source, identified by your organization’s name or ID (for example, audit_logs('my-org')). See Querying by name for details. No additional configuration is required to query them. Run a query from the SQL sandbox, the bt sql CLI, or the API. Examples:

Recent activity across the organization

SELECT created, actor_id, event_type, resource_type, resource_name
FROM audit_logs('<org>') -- Replace with your organization name or ID
WHERE created > NOW() - INTERVAL 1 DAY
ORDER BY created DESC
LIMIT 100

All actions taken by a specific member

SELECT created, event_type, resource_type, resource_name
FROM audit_logs('<org>') -- Replace with your organization name or ID
WHERE actor_id = '<user_id>' -- Replace with the member's user ID
ORDER BY created DESC

Permission and access control changes in the last 30 days

SELECT created, actor_id, event_type, resource_name, after_changes
FROM audit_logs('<org>') -- Replace with your organization name or ID
WHERE created > NOW() - INTERVAL 30 DAY
  AND (event_type LIKE 'acl.%' OR event_type LIKE 'group%' OR event_type LIKE 'role%')
ORDER BY created DESC

To log reads of your data in the audit trail, see Audit data reads and modifications.

What gets logged

Each audit log entry records a single event: what happened, who performed it, and what changed.

Fields

Each organization audit log entry includes:

Field	Description
`created`	Event timestamp.
`org_id`	Organization where the event occurred.
`project_id`	Project associated with the event, when applicable.
`actor_id`	User or service account that performed the action.
`event_type`	Event name in `<resource>.<action>` form, such as `project.updated`.
`event_details`	Additional event-specific metadata.
`resource_type`	Type of resource that changed.
`resource_id`	ID of the resource that changed.
`resource_name`	Human-readable resource name.
`actor_details`	Request metadata, including IP address, user agent, request ID, and authentication token details.
`before_changes`	Relevant resource fields before the event. Populated for update and delete events.
`after_changes`	Relevant resource fields after the event. Populated for create and update events.

For create events, before_changes is null. For delete events, after_changes is null. For update events, both fields contain the changed resource values. Readonly events contain neither.

Events

Braintrust records organization audit log events for these resource categories:

Resource category	Resource types	Event types
Organizations	`organization`	`organization.created`, `organization.updated`
Projects	`project`	`project.created`, `project.updated`, `project.deleted`
Experiments	`experiment`	`experiment.created`, `experiment.updated`, `experiment.deleted`
Datasets	`dataset`	`dataset.created`, `dataset.updated`, `dataset.deleted`
Organization AI providers and secrets	`ai_secret`	`ai_secret.created`, `ai_secret.updated`, `ai_secret.deleted`
API keys	`api_key`	`api_key.created`, `api_key.deleted`
Data plane manager service tokens	`service_token`	`data_plane_service_token.created`, `data_plane_service_token.replaced`
Permission groups	`group`	`group.created`, `group.updated`, `group.deleted`
Permission group membership	`group_member`	`group_member.created`, `group_member.deleted`
Roles	`role`	`role.created`, `role.updated`, `role.deleted`
Role membership	`role_member`	`role_member.created`, `role_member.deleted`
Role permissions	`role_permission`	`role_permission.created`, `role_permission.deleted`
Organization members	`org_member`	`org_member.created`, `org_member.deleted`
Access grants	`acl`	`acl.created`, `acl.deleted`

Some operations emit multiple audit log entries. For example, inviting a user can create an organization member entry, permission group membership entries, access grants, and an API key entry. Bulk operations create one audit log entry per changed resource.

Audit logs can take a few minutes to show up after an action occurs.

Sensitive values

Braintrust excludes or redacts sensitive values in audit logs:

API key hashes and raw keys are not included. Audit entries include the API key preview name when available.
AI provider secrets are redacted. Audit entries include a secret preview and omit encrypted secret material and key names.
Resource IDs, organization IDs, project IDs, creation timestamps, update timestamps, and deletion timestamps are omitted from before_changes and after_changes when they would add noise to the change diff.

Audit data reads and modifications

Braintrust can record row-level audit logs for certain kinds of resources. These can be high volume and are disabled by default. query.read events are particularly high volume. When enabled, query.read covers both SQL queries run manually and ones run implicitly by the Braintrust UI when you browse logs, experiments, and traces. Braintrust records the following events for data rows:

Resource category	Resource types	Event types
SQL queries	`query`	`query.read`
Logs and spans	`project_log`	`project_log.deleted`
Experiment rows	`experiment_log`	`experiment_log.deleted`
Dataset rows	`dataset_log`	`dataset_log.deleted`

To enable row-level audit logging for your organization, contact Braintrust support.

Next steps

Access control to learn how organization permissions work.
Manage permissions to grant Read audit logs to a permission group.
SQL reference to learn about how to query audit logs with SQL.

​Grant access

​View the audit log

​Query the audit log

​What gets logged

​Fields

​Events

​Sensitive values

​Audit data reads and modifications

​Next steps

Grant access

View the audit log

Query the audit log

What gets logged

Fields

Events

Sensitive values

Audit data reads and modifications

Next steps