Filter and search logs

Narrow down to specific traces by applying a filter via the UI, CLI, or API. Paste ready-made patterns from Common filters, or save a useful combination as a shared table view. When you don’t have an exact filter in mind, switch to deep search or Loop.

Apply a filter

Select Filter to open the filter menu:

Basic: Point-and-click filtering for common fields.
SQL: Write precise SQL queries with operators, functions, and full-text search. Use the Generate button to create queries from natural-language descriptions. See SQL best practices performance tips.

When viewing traces (set in Display > Row type), Basic filter conditions match across spans automatically.

SQL queries on project logs enforce your plan’s data retention limit. Use a relative interval to stay within the window. See Plans and limits for retention details.

Use bt sql to run filtered SQL queries against your logs from the terminal. Pass a query inline or pipe one in from a file.

bt sql "SELECT * FROM project_logs('my-project') WHERE scores.Factuality > 0.8 LIMIT 100"

cat analysis.sql | bt sql

For automated workflows, pass --non-interactive to skip the interactive interface and --json to get machine-readable output.

bt sql --non-interactive "SELECT count(*) FROM project_logs('my-project') WHERE tags MATCH 'error'" --json

Query logs programmatically using the Braintrust API for automation, integrations, and custom tooling.Basic filtering: Use the project logs endpoint for simple filters and programmatic access:

curl -X GET "https://api.braintrust.dev/v1/project/<PROJECT_ID>/logs" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

SQL queries: For complex queries, POST a SQL query to the /btql endpoint:

curl -X POST https://api.braintrust.dev/btql \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM project_logs('"'<PROJECT_ID>'"') WHERE scores.Factuality > 0.8 LIMIT 100"
  }'

The API accepts these parameters:

query (required): Your SQL query string.
fmt: Response format (json or parquet, defaults to json).
tz_offset: Timezone offset in minutes for correct day boundaries.
audit_log: Include audit log data.

Common filters

Ready-to-use filter expressions for the most common log queries. Paste them directly into the SQL filter tab in the UI, or use them as the WHERE clause in bt sql or /btql API queries.

Filter by score

scores.Factuality > 0.8

Filter by tag

tags MATCH "error"

Filter errored runs

error IS NOT NULL

Filter by metadata

metadata.user_id = "user-123"

Search text fields

Use search() to match across all text fields, or MATCH to target a single field. See Full-text search for details.

search('timeout')

Filter by time

Use a relative interval to stay within your plan’s data retention window.

created > now() - interval 1 day

Match traces across spans

When filtering traces, you often want to match against any span in the trace, not just the root. Wrap conditions in ANY_SPAN(). For example, to find traces with both an LLM call and an error somewhere in the tree:

ANY_SPAN(span_attributes.type = 'llm') AND ANY_SPAN(error IS NOT NULL)

See Single span filters for nesting rules and the is_root restriction.

Braintrust applies ANY_SPAN() automatically in:

The Basic filter tab when Display > Row type is set to Traces.
Topics automation filters.
Trace-scoped online scoring rule filters.

Save a frequently-used combination of filters, display settings, and columns as a custom table view. Saved views appear in the menu at the top of the table and are visible to all project members. If you’ve built a useful view in one project, you can duplicate it to another project via the API.

Ask questions with Loop

Select Loop on the Logs page to ask natural language questions about your traces. Loop understands your data structure and can answer questions, identify patterns, and surface specific traces without writing any queries. Example questions:

“Show me traces where the user was confused”
“Find requests that took longer than usual”
“What are the most common error patterns?”

You can also select one or more rows and use Find similar traces. Loop identifies common traits across the selected traces and returns semantically similar ones. Loop is also available when viewing an individual trace. Ask questions like “Summarize this trace” or “Why did this request fail?” See Analyze logs and Analyze individual traces for more details.

Find traces with deep search

Deep search finds traces based on semantic similarity rather than keyword matching or exact filters. It’s useful for discovering patterns, sentiment, and edge cases that SQL filters would miss. For example, you can find traces where users expressed frustration, even if the word “frustrated” never appears. See Use deep search for detailed examples and workflows.

Speed up log filtering

If you frequently filter on the same custom fields, you can index them to reduce query latency. Braintrust offers two options: A full-text index for broad search and subfield indexes for specific fields you filter on most.

Go to Settings > Advanced.
Under Log search optimization, enable the toggle to build a full-text index that speeds up text-based filter queries.
Under Subfield indexing, click + Add subfield index for each field you filter on frequently. Braintrust auto-discovers candidate fields from your data (e.g., metadata.session_id). If a field doesn’t appear, you can type it in directly. Subfield paths must start with input, output, expected, metadata, or span_attributes.
Click Save and index.
Enter how many days back to backfill (default: 3) and click Save and backfill.

The Index status section shows backfill progress as indexing runs in the background.

Use search() in SQL filters to query all text fields at once. It gets automatic bloom filter acceleration when log search optimization is on.

Next steps

Use deep search for semantic queries
Score online to evaluate filtered traces
Create dashboards with filtered metrics
Read the SQL reference for complete query syntax

Documentation Index

​Apply a filter

​Common filters

​Save and share filters

​Ask questions with Loop

​Find traces with deep search

​Speed up log filtering

​Next steps

Apply a filter

Common filters

Save and share filters

Ask questions with Loop

Find traces with deep search

Speed up log filtering

Next steps