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

> Manage Topics automations and real-time message streams in Braintrust

`bt topics` manages [Topics automations](/observe/topics) for the active project.

Running `bt topics` with no subcommand is equivalent to `bt topics status`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics open
```

## bt topics config

View or edit Topics automation configuration.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config delete
bt topics config delete --automation-id <ID>
bt topics config delete --force
```

<Warning>
  Deleting an automation is irreversible. The automation configuration, topic maps, and scheduling settings cannot be recovered after deletion.
</Warning>

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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

<Note>
  This is an advanced debugging command. Use it to share a topic map's output with Braintrust when troubleshooting clustering behavior.
</Note>

Download the saved report for a [topic map](/observe/topics) 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](/observe/topics/manage#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`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 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

<Note>
  This is an advanced debugging command. Use it to share a topic map's raw artifact with Braintrust when troubleshooting clustering behavior.
</Note>

Download the raw `.btmap` artifact for a [topic map](/observe/topics). This is the low-level binary topic map that underlies the [report](#bt-topics-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`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 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)           |