> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit logging

> Track and review administrative actions in your Braintrust organization, such as permission changes, member management, and API key creation

export const feature_0 = "Audit logging"

export const verb_0 = "is"

The [**<Icon icon="clipboard-list" /> Audit log**](https://www.braintrust.dev/app/~/configuration/org/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.

<Note>
  {feature_0} {verb_0} only available on the [Enterprise plan](/plans-and-limits#plans).
</Note>

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.

<Note>
  Audit logging is not yet available for self-hosted deployments.
</Note>

## Grant access

Members of the [**Owners**](/admin/access-control#built-in-permission-groups) permission group can read organization audit logs by default. To let anyone else read them, grant the organization-level **Read audit logs** permission in **<Icon icon="settings-2" /> Settings** > [**<Icon icon="shield-check" /> Permission groups**](https://www.braintrust.dev/app/~/configuration/org/groups).

<Note>
  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.
</Note>

## View the audit log

To view recent organization activity, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="clipboard-list" /> Audit log**](https://www.braintrust.dev/app/~/configuration/org/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 <Icon icon="asterisk" /> **Open SQL sandbox**. See [Audit data reads](#audit-data-reads) and the [SQL reference](/reference/sql) for query details.

## Query the audit log

Users with the **Read audit logs** permission can query audit logs with [SQL](/reference/sql) using the `audit_logs('<org_id>')` data source. No additional configuration is required to query them.

Run a query from the [**<Icon icon="asterisk" /> SQL sandbox**](https://www.braintrust.dev/app/~/sql), the [`bt sql`](/reference/cli/sql) CLI, or the [API](/reference/sql#api).

**Examples:**

```sql Recent activity across the organization theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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
```

```sql All actions taken by a specific member theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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
```

```sql Permission and access control changes in the last 30 days theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](#audit-data-reads).

## 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`                 |
| 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.

<Note>
  Audit logs can take a few minutes to show up after an action occurs.
</Note>

### 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

Braintrust can record reads of your organization's data as audit log entries. This covers both SQL queries run manually and ones run implicitly by the Braintrust UI when you browse logs, experiments, and traces. Because every data read is logged, this can produce a high volume of audit logs and is recommended only for organizations with strict data access auditing requirements.

Braintrust records the following event for data reads:

| Resource category | Resource types | Event types  |
| ----------------- | -------------- | ------------ |
| SQL queries       | `query`        | `query.read` |

To enable data read audit logging for your organization, contact [Braintrust support](mailto:support@braintrust.dev).

## Next steps

* [Access control](/admin/access-control) to learn how organization permissions work.
* [Manage permissions](/admin/access-control/manage-permissions) to grant **Read audit logs** to a permission group.
* [SQL reference](/reference/sql) to learn about how to query audit logs with SQL.