bt topics

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.

bt topics poke

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 open

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

Accepts the same flags as 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

This is an advanced debugging command. Use it to share a topic map’s output with Braintrust when troubleshooting clustering behavior.

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

This is an advanced debugging command. Use it to share a topic map’s raw artifact with Braintrust when troubleshooting clustering behavior.

Download the raw .btmap artifact for a topic map. This is the low-level binary topic map that underlies the report. 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)

API

CLI

SQL

bt topics status

Flags

bt topics poke

bt topics rewind

Arguments

Flags

bt topics open

bt topics config

Flags

bt topics config enable

bt topics config delete

bt topics config set

bt topics config topic-map set

bt topics report

Flags

bt topics btmap

Flags

​bt topics status

​Flags

​bt topics poke

​bt topics rewind

​Arguments

​Flags

​bt topics open

​bt topics config

​Flags

​bt topics config enable

​bt topics config delete

​bt topics config set

​bt topics config topic-map set

​bt topics report

​Flags

​bt topics btmap

​Flags

bt topics status

Flags

bt topics poke

bt topics rewind

Arguments

Flags

bt topics open

bt topics config

Flags

bt topics config enable

bt topics config delete

bt topics config set

bt topics config topic-map set

bt topics report

Flags

bt topics btmap

Flags