Skip to main content
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('<org_id>') data source. 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_id>') -- Replace with your organization 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_id>') -- Replace with your organization 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_id>') -- Replace with your organization 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:
FieldDescription
createdEvent timestamp.
org_idOrganization where the event occurred.
project_idProject associated with the event, when applicable.
actor_idUser or service account that performed the action.
event_typeEvent name in <resource>.<action> form, such as project.updated.
event_detailsAdditional event-specific metadata.
resource_typeType of resource that changed.
resource_idID of the resource that changed.
resource_nameHuman-readable resource name.
actor_detailsRequest metadata, including IP address, user agent, request ID, and authentication token details.
before_changesRelevant resource fields before the event. Populated for update and delete events.
after_changesRelevant 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 categoryResource typesEvent types
Organizationsorganizationorganization.created, organization.updated
Projectsprojectproject.created, project.updated, project.deleted
Experimentsexperimentexperiment.created, experiment.updated, experiment.deleted
Datasetsdatasetdataset.created, dataset.updated, dataset.deleted
Organization AI providers and secretsai_secretai_secret.created, ai_secret.updated, ai_secret.deleted
API keysapi_keyapi_key.created, api_key.deleted
Data plane manager service tokensservice_tokendata_plane_service_token.created, data_plane_service_token.replaced
Permission groupsgroupgroup.created, group.updated, group.deleted
Permission group membershipgroup_membergroup_member.created, group_member.deleted
Rolesrolerole.created, role.updated, role.deleted
Role membershiprole_memberrole_member.created, role_member.deleted
Role permissionsrole_permissionrole_permission.created, role_permission.deleted
Organization membersorg_memberorg_member.created, org_member.deleted
Access grantsaclacl.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 categoryResource typesEvent types
SQL queriesqueryquery.read
Logs and spansproject_logproject_log.deleted
Experiment rowsexperiment_logexperiment_log.deleted
Dataset rowsdataset_logdataset_log.deleted
To enable row-level audit logging for your organization, contact Braintrust support.

​
Next steps