Copy page

Braintrust

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 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
• Query by SQL (BTQL) API Reference
• BTQL Reference
• BTQL Rate Limits
• Braintrust Audit Logs Retention

Sample Record

Code
{
  "_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
}