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, ask Loop.

Apply a filter

On hosted Braintrust, queries against logs and playground data enforce your plan’s data retention window (14-day retention on Starter, 30-day retention on Pro by default) across every query path: the UI, CLI, API, and MCP. Experiments have up to 365-day retention on all plans. Data older than the window is silently filtered out rather than returned as an error, so use a relative interval to stay within the window. Plans without a retention limit, such as Enterprise with custom retention, aren’t affected.

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.

As you type in the search bar, the dropdown shows Suggestions with field name completions and Recent with your most recent text searches and SQL filters. When Loop is enabled, select Generate SQL with Loop to open the SQL filter editor with your text pre-filled as a prompt.Applied filters appear as chips in the filter bar. To edit a text search chip, click it to open an inline editor and select Update.When viewing traces (set in Display > Row type), Basic filter conditions match across spans automatically.

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.

Most SQL data-source functions also accept an object name in place of its ID. See Querying by name.

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.

Identify spans and traces

Every span carries three ID fields, each with a distinct role:

Field	Identifies	Use it to
`id`	An individual span (one row in logs or an experiment).	Filter to or link to a single span. This is the span’s identifier.
`root_span_id`	The entire trace the span belongs to.	Filter to or link to a full trace.
`span_id`	An internal field used with `span_parents` to construct the span tree.	Nothing. Treat it as an implementation detail.

To fetch a known span or trace, filter on id or root_span_id. Both map directly to the index, so they are the fastest predicates. Avoid filtering on span_id. See Fetch known traces or spans by ID for details. When you link to a trace in the Braintrust UI, the r= URL parameter is the root_span_id, not the id. Using the root_span_id is the efficient way to open a trace. See Link to a trace or span.

Some ingestion paths, such as OpenTelemetry collectors, set span_id to the same value as id, which is why the two are often conflated. Regardless, id is the field that identifies a span.

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

scores.Factuality IS NULL OR scores.Factuality < 0.5

Filter by tag

tags MATCH "error"

NOT tags MATCH "internal"

Filter errored runs

error IS NOT NULL

Filter by metadata

metadata.user_id = "user-123"

metadata.environment = "production" AND metadata.model = "gpt-5-mini"

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')

output MATCH 'timeout'

Filter by time

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

created > now() - interval 1 day

created >= '2024-01-01' AND created < '2024-02-01'

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

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 Shingled search optimization, enable the toggle to also index multi-word phrases, which speeds up phrase and multi-word search() 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

Score online to evaluate filtered traces
Create dashboards with filtered metrics
Read the SQL reference for complete query syntax

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Filter and search logs

Apply a filter

Identify spans and traces

Common filters

Ask questions with Loop

Speed up log filtering

Next steps

​Apply a filter

​Identify spans and traces

​Common filters

​Save and share filters

​Ask questions with Loop

​Speed up log filtering

​Next steps

Apply a filter

Identify spans and traces

Common filters

Save and share filters

Ask questions with Loop

Speed up log filtering

Next steps