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
bt topics config delete # Delete the Topics automation for this project
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. Matches if any span in the trace satisfies the condition. |
--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 delete
Permanently delete the Topics automation for the active project.
bt topics config delete
bt topics config delete --automation-id <ID>
bt topics config delete --force
Deleting an automation is irreversible. The automation configuration, topic maps, and scheduling settings cannot be recovered after deletion.
| Flag | Description |
|---|
--automation-id <ID> | Target a specific automation by ID |
--force / -f | Skip the confirmation prompt |
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 |
bt topics report
Download the saved report for a topic map as JSON. The report is the generated clustering result, including topic names and cluster structure. It’s the saved output that Topics reconciles against when re-generating, so topic names stay stable across runs (see Tune clustering settings). Use it to inspect, archive, or analyze a topic map’s output outside Braintrust.
Identify the topic map by its function ID, which you can find with bt topics config. The report writes to stdout unless you pass --output.
# Print the latest report to stdout
bt topics report fn_123
# Download a specific version to a file
bt topics report fn_123 --version 0000000000000001 --output report.json
Flags
| Flag | Description |
|---|
--id <FUNCTION_ID> | Topic map function ID (also accepted as a positional argument) |
--version <XACT_ID> | Download a specific topic map version (default: the latest) |
--output <PATH> | Write the report JSON to a file (default: stdout) |
bt topics btmap
Download the raw .btmap artifact for a topic map. This is the low-level binary topic map that underlies the report. Use it for advanced inspection or to archive the raw artifact. Most users want bt topics report instead, which returns human-readable JSON.
Identify the topic map by its function ID, which you can find with bt topics config. The artifact writes to stdout unless you pass --output.
# Write the latest .btmap artifact to a file
bt topics btmap fn_123 --output topic-map.btmap
# Download a specific version
bt topics btmap fn_123 --version 0000000000000001 --output topic-map.btmap
Flags
| Flag | Description |
|---|
--id <FUNCTION_ID> | Topic map function ID (also accepted as a positional argument) |
--version <XACT_ID> | Download a specific topic map version (default: the latest) |
--output <PATH> | Write the .btmap bytes to a file (default: stdout) |
