Documentation Index
Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
bt topics manages Topics automations for the active project.
Running bt topics with no subcommand is equivalent to bt topics status.
bt topics # Show Topics status for the active project
bt topics status # Same as above
bt topics poke # Queue Topics to run on the next executor pass
bt topics rewind 7d # Rewind and reprocess the last 7 days of history
bt topics open # Open the Topics page in the browser
bt topics config # View Topics automation config
bt topics status
Show the Topics automation status for the active project.
bt topics status
bt topics status --full
bt topics status --watch
Flags
| Flag | Description |
|---|
--full | Show expanded diagnostics, including the internal state machine |
--watch | Refresh every 2 seconds until interrupted |
--json | Output as JSON (incompatible with --watch) |
bt topics poke
Queue Topics to run on the next executor pass. Use this to trigger immediate processing without waiting for the next scheduled run.
Output lists all topic automations queued for processing, showing each automation’s name, ID, and scheduled timing.
bt topics rewind
Rewind recent Topics history and queue it to reprocess. Traces in the specified window will have their facets and topic labels recomputed on the next executor pass.
bt topics rewind 7d # Rewind the last 7 days
bt topics rewind 1h # Rewind the last hour
bt topics rewind 30m --automation-id <ID> # Rewind a specific automation
Arguments
| Argument | Description |
|---|
<DURATION> | Time window to rewind. Format: <NUMBER><UNIT> where unit is s (seconds), m (minutes), h (hours), d (days), or w (weeks). Example: 7d, 1h, 30m |
Flags
| Flag | Description |
|---|
--automation-id <ID> | Rewind a specific automation by ID |
--json | Output as JSON |
bt topics open
Open the Topics page for the active project in the browser.
bt topics config
View or edit Topics automation configuration.
bt topics config # View all automations
bt topics config --automation-id <ID> # View a specific automation
Flags
| Flag | Description |
|---|
--automation-id <ID> | Target a specific automation by ID |
--json | Output as JSON |
bt topics config enable
Enable Topics for the active project with the provided configuration.
bt topics config enable
bt topics config enable --name "My automation" --topic-window 1d --generation-cadence 1h
bt topics config enable --filter "span_type = 'llm'" --sampling-rate 25
| Flag | Description |
|---|
--name <NAME> | Human-friendly automation name |
--description <DESC> | Human-friendly automation description |
--topic-window <DURATION> | Topic window duration (e.g., 1h, 1d) |
--generation-cadence <DURATION> | How often to generate fresh topic maps (e.g., 1h, 1d) |
--relabel-overlap <DURATION> | Relabel overlap duration (e.g., 1h) |
--idle-time <DURATION> | Trace idle wait duration before processing (e.g., 30s) |
--sampling-rate <PERCENT> | Percent of matching traces to sample (e.g., 25 or 25%) |
--filter <EXPR> | SQL filter to select which traces get facets and topic labels |
--facet <NAME> | Facet labels to enable (repeatable; uses built-in defaults if omitted) |
--embedding-model <MODEL> | Embedding model for new topic maps |
bt topics config set
Update editable Topics configuration fields for an existing automation. Only the fields you specify are changed.
bt topics config set --topic-window 2d
bt topics config set --sampling-rate 50 --automation-id <ID>
bt topics config set --clear-filter
bt topics config enable, plus:
| Flag | Description |
|---|
--clear-filter | Clear the top-level SQL filter (conflicts with --filter) |
bt topics config topic-map set
Update a configured topic map by name or function ID.
bt topics config topic-map set <TOPIC_MAP>
bt topics config topic-map set my-map --algorithm kmeans --n-clusters 10
| Argument/Flag | Description |
|---|
<TOPIC_MAP> | Topic map name or function ID (required) |
--name <NAME> | Human-friendly topic map name |
--description <DESC> | Human-friendly topic map description |
--source-facet <FACET> | Facet field this topic map clusters |
--embedding-model <MODEL> | Embedding model for clustering |
--distance-threshold <FLOAT> | Maximum centroid distance before returning no_match |
--algorithm <ALGO> | Clustering algorithm: hdbscan or kmeans |
--dimension-reduction <METHOD> | Dimension reduction method: umap, pca, or none |
--sample-size <NUM> | Maximum rows sampled during topic map generation |
--n-clusters <NUM> | Number of clusters (kmeans only) |
--min-cluster-size <NUM> | Minimum cluster size (hdbscan only) |
--min-samples <NUM> | Minimum samples (hdbscan only) |
--hierarchy-threshold <NUM> | Hierarchy threshold for naming hierarchical clusters |
--naming-model <MODEL> | LLM model used to name generated topics |
--disable-reconciliation <BOOL> | Disable reconciliation against previously saved reports |
