Skip to main content
Alerts notify you when conditions are met on production logs. Send notifications to webhooks or Slack channels to catch errors, track quality issues, or monitor usage patterns.
For hybrid deployments, alerts are available starting with v0.0.72. The Slack integration is available starting with v1.1.29.

​
Create an alert

Enable the Slack integration before creating an alert to send to a Slack channel.
  1. Go to Settings.
  2. Under Project, select Alerts.
  3. Click + Alert.
  4. Enter alert name.
  5. Configure alert conditions:
    • SQL filter: Query that defines which logs trigger the alert.
    • Interval: How often to check for matching logs (5 min, 30 min, 1 hr, 4 hr, 12 hr, 24 hr).
  6. Select action type: Webhook or Slack.
  7. Configure the action (see below).
  8. Click Test alert to verify configuration.
  9. Click Save.

​
Configure webhooks

Send JSON payloads to custom endpoints:
  1. Select Webhook as the action type.
  2. Enter your webhook URL.
  3. Optionally add custom headers for authentication.

​
Webhook payload

Alerts send this JSON structure: 
{
  "organization": {
    "id": "org_123",
    "name": "your-organization"
  },
  "project": {
    "id": "proj_456",
    "name": "your-project"
  },
  "automation": {
    "id": "c5b32408-8568-4bff-9299-8cdd56979b67",
    "name": "High-Priority Factuality",
    "description": "Alert on factuality scores for priority logs",
    "event_type": "logs",
    "btql_filter": "metadata.priority = 0 AND scores.Factuality < 0.9",
    "interval_seconds": 3600,
    "url": "https://braintrust.dev/app/your-org/p/your-project/configuration/alerts?aid=..."
  },
  "details": {
    "is_test": false,
    "message": "High-Priority Factuality: 5 logs triggered alert in the last 1 hour",
    "time_start": "2025-05-12T10:00:00.000Z",
    "time_end": "2025-05-12T11:00:00.000Z",
    "count": 5,
    "related_logs_url": "https://braintrust.dev/app/your-org/p/your-project/logs?search=..."
  }
}
Use the payload to:
  • Log alerts to monitoring systems
  • Create tickets in issue trackers
  • Send formatted messages to communication tools
  • Trigger automated responses or remediation

​
Configure Slack

Send messages directly to Slack channels:
  1. Enable the Slack integration in your organization settings.
  2. Select Slack as the action type.
  3. Select a Slack channel using the searchable dropdown. The channel list refreshes automatically every 7 days. To trigger a manual refresh, click Refresh channels. If your channel doesn’t appear, you can enter its channel ID manually. To find a channel ID in Slack:
    1. Right-click the channel name.
    2. Click View channel details.
    3. Scroll to the bottom and copy the channel ID.

​
Large workspaces

For workspaces with more than 100,000 channels, the channel list shows the most recently active channels. If your target channel doesn’t appear, use the manual channel ID entry option.

​
Slack alert format

Slack alerts include:
  • Alert name and description.
  • Number of matching logs.
  • Time range.
  • Link to view matching logs in Braintrust.

​
Write SQL filters

Filters define which logs trigger alerts. Use SQL to match specific conditions:

​
Error alerts

error IS NOT NULL
Alert when any log contains an error.

​
Quality thresholds

scores.factuality < 0.8 AND metadata.environment = 'production'
Alert when factuality scores drop below 0.8 in production.

​
High-cost requests

metrics.estimated_cost > 1.0
Alert on expensive requests exceeding $1.

​
Specific users or features

metadata.user_tier = 'enterprise' AND metadata.feature = 'summarization'
Alert on logs from enterprise users using the summarization feature.

​
Combined conditions

(scores.accuracy < 0.7 OR error IS NOT NULL) AND metadata.priority = 'high'
Alert on low accuracy or errors for high-priority requests.

​
Test alerts

Before saving, test alerts to verify they work:
  1. Click Test alert in the alert configuration.
  2. Braintrust runs the filter on recent logs.
  3. If matching logs exist, a test payload is sent.
  4. Check your webhook endpoint or Slack channel for the test message.
If no matching logs are found:
  • Adjust your BTQL filter to match actual log patterns.
  • Increase the alert interval to check more historical data.
  • Verify logs are being sent to the project.

​
Common alert patterns

​
Error monitoring

Alert on any error in production: 
error IS NOT NULL AND metadata.environment = 'production'

​
Quality degradation

Alert when average scores drop: 
scores.quality < 0.9
Run this hourly to catch quality regressions.

​
Usage spikes

Alert when request volume exceeds normal levels. Use external systems to track historical rates and webhook alerts to capture spikes.

​
Specific model issues

Alert on problems with a particular model: 
metadata.model = 'gpt-4o' AND (error IS NOT NULL OR scores.accuracy < 0.8)

​
Next steps