# Audit Logs

Ingests Braintrust audit log events — administrative and security-relevant actions across an Enterprise organization — via the BTQL SQL-over-HTTP API.

**Sync Type: Incremental**

## Prerequisites

Before configuring this input, you need:

1. **A Braintrust Enterprise-plan organization.** Audit logs are an Enterprise-only feature — they are not available on Free or Pro plans.
2. **An API key belonging to a role with the "Read audit logs" permission.** By default, only the **Owners** group has this permission. If the key's role lacks it, requests fail with a `403 Forbidden` even on an Enterprise plan.
3. **Your Braintrust organization name or ID.** The organization ID (a UUID) is preferred over the name, since it's stable if the organization is ever renamed.

## Authentication

This input authenticates with a Braintrust **API key**, sent as a Bearer token.

1. Log in to Braintrust and go to **Settings** → **API keys**.
2. Create a new API key (or use an existing one) that belongs to a role with the **Read audit logs** permission.
3. Copy the key and store it securely — Braintrust only shows it once.
4. Note your **Organization ID** — you'll need it to configure the input. It's visible in your organization's settings page.

See vendor documentation for how to locate or create roles with the "Read audit logs" permission.

## Configuration

### Settings

| Setting | Type | Required | Description |
| ------- | ---- | -------- | ----------- |
| Organization ID | string | Yes | Braintrust organization ID(UUID). |
| Base URL | string | No | Braintrust API host. Defaults to `https://api.braintrust.dev` (US). Use `https://api-eu.braintrust.dev` for the EU region. For a self-hosted instance, use that instance's data-plane URL. |
| Backfill Start Time | string | No | The date to start fetching data from. If not specified, no past records will be fetched. |
| Use synthetic data | boolean | No | Generate synthetic data for testing, instead of connecting to a real data source. |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |

### Secrets

| Secret | Type | Required | Description |
| ------ | ---- | -------- | ----------- |
| API Key | string | Yes | Braintrust API key. Must belong to a role with the "Read audit logs" permission on an Enterprise-plan organization. |

## Setup Walk-through

1. In Braintrust, go to **Settings** → **API keys** and create (or copy) an API key belonging to a role with the **Read audit logs** permission.
2. Note your Braintrust **Organization ID** (or name).
3. In Monad, create a new Braintrust Audit Logs input.
4. Enter the **Organization** value from step 2.
5. If your organization is on the EU region or a self-hosted deployment, set **Base URL** accordingly; otherwise leave it blank for the US default.
6. Paste the API key from step 1 into the **API Key** secret field.
7. Optionally set a **Backfill Start Time** to control how far back the first sync reaches.
8. Save and start the input.

## Troubleshooting

### Common Issues

#### 1. Authentication Failures (401 Unauthorized)

**Symptoms**: The connection fails with an unauthorized error.

**Causes**:

- The API key is incorrect, revoked, or was copied with extra whitespace.

**Solutions**:

- Regenerate the API key in **Settings** → **API keys** and update the input's secret.

#### 2. Permission Denied (403 Forbidden)

**Symptoms**: The connection fails with a forbidden error.

**Causes**:

- The organization is not on an Enterprise plan, or
- The API key's role does not have the **Read audit logs** permission (default: **Owners** group only).

**Solutions**:

- Confirm the organization's plan is Enterprise.
- Confirm the API key's role has been granted **Read audit logs**, or use a key from a role that has it (e.g. Owners).

#### 3. No Audit Logs Appearing

**Symptoms**: The input runs successfully but returns no records.

**Causes**:

- No administrative or security-relevant events have occurred in the queried time range.
- **Backfill Start Time** is set too far in the future, or left unset on an org with only historical activity.

**Solutions**:

- Verify audit-relevant activity (e.g. API key or ACL changes) has occurred in the organization.
- Set **Backfill Start Time** to an earlier date to widen the window.

#### 4. Rate Limit Exceeded (429 Too Many Requests)

**Symptoms**: Requests intermittently fail with a rate-limit error.

**Causes**:

- BTQL's request budget is shared org-wide across the Braintrust UI, CLI, MCP, and this input.

**Solutions**:

- The input polls conservatively by default; if you're hitting limits, lower the **API Rate Limit** setting or reduce concurrent BTQL usage from other tools against the same organization.

#### 5. Wrong Base URL / Region

**Symptoms**: Authentication or queries fail even though the API key and organization look correct.

**Causes**:

- The organization is hosted in the EU region or on a self-hosted data plane, but **Base URL** was left at the US default (or vice versa).

**Solutions**:

- Set **Base URL** to `https://api-eu.braintrust.dev` for EU organizations, or to your self-hosted data-plane URL. Leave it blank only for US-hosted organizations.

## Related Articles

- [Braintrust Audit Logs](https://www.braintrust.dev/docs/admin/audit-logs)
- [Query by SQL (BTQL) API Reference](https://www.braintrust.dev/docs/api-reference/query)
- [BTQL Reference](https://www.braintrust.dev/docs/reference/btql)
- [BTQL Rate Limits](https://www.braintrust.dev/docs/kb/btql-rate-limits-on-free-and-pro-plans)
- [Braintrust Audit Logs Retention](https://www.braintrust.dev/docs/admin/audit-logs#retention)


## Sample Record
```json
{
  "_xact_id": "f7b0e0a5-85e8-d986-8265-4eb6d28ce593",
  "_pagination_key": "03d8d2b7-96ce-3a4d-4814-93dd1e607556",
  "created": "2026-08-14T13:08:15.214261Z",
  "org_id": "536cc6f4-3f84-58dd-ea1a-d80cd2403a1f",
  "project_id": null,
  "actor_id": "user:2aa29ab6-60c2-fa04-1b7b-90cea9537268",
  "actor_details": {
    "ip": "94.210.223.152",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
    "request_id": "b0b9beb8-eadb-a658-4019-af2cf370bb31",
    "auth": "session"
  },
  "event_type": "role.created",
  "event_details": {
    "source": "cli",
    "success": true
  },
  "resource_type": "role",
  "resource_id": "0eb7d080-c94d-6ddc-8b82-7f841dfd801d",
  "resource_name": "read-only-role",
  "before_changes": null,
  "after_changes": null
}
```