> ## 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.
# Manage Topics
> Keep the Topics pipeline healthy: check status, trigger runs on demand, adjust sampling, pause, and rewind history after facet or filter changes.
Once Topics is enabled, the pipeline runs on a daily cycle. This page covers the operations you'll perform to keep it healthy: checking status, triggering runs on demand, tuning what gets processed, and replaying history.
For facet-specific operations (creating, editing, deleting facets), see [Custom facets](/observe/topics/custom-facets).
## Check automation status
Topics runs as a daily pipeline. To see a live indicator of the current stage:
Go to the [** Topics**](https://www.braintrust.dev/app/~/topics) page. The **Topics automation status** panel shows:
* Current pipeline state and when it was entered.
* Next scheduled topic generation time.
* Active facets, with health indicators for any unhealthy references.
* Facet coverage per facet: traces **matched** (facet produced a usable summary), **processed** (ran through the facet pipeline at all), **running**, and **errored**.
* The most recent error, if any.
The Logs-page ** Topics > Status** dialog provides the same information.
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics status # current stage
bt topics status --full # expanded diagnostics including state machine
bt topics status --watch # refresh every 2 seconds until interrupted
```
See [`bt topics status`](/reference/cli/topics#bt-topics-status) for all flags.
The pipeline moves through these stages:
| Stage | Meaning |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Idle** | Waiting until the next scheduled run. Trigger a run immediately with [Re-generate topics](#re-generate-topics). |
| **Waiting for facets** | Waiting for at least 100 processed traces before generating topics. |
| **Recomputing topics** | Generating new topics based on collected facet summaries. |
| **Pending logs processing** | New topics generated; preparing to apply classifications to existing logs. |
| **Processing logs** | Applying newly generated topics to existing logs. |
## Re-generate topics
Trigger an immediate run of the topic generation pipeline instead of waiting for the next daily cycle. Useful after enabling Topics, after raising the sampling rate, or whenever you want fresher classifications now.
Click ** Re-generate topics** in the **Topics automation status** panel on the [** Topics**](https://www.braintrust.dev/app/~/topics) page.
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics poke
```
See [`bt topics poke`](/reference/cli/topics#bt-topics-poke) for all flags.
## Group traces into conversations
When a session or multi-turn conversation spans multiple traces, configure Topics to classify the group as a single unit instead of each trace independently. Group traces by a key like `metadata.session_id` or `metadata.conversation_id`. This is the typical setup for [auto-instrumented](/instrument) applications, where each LLM call lands in its own trace.
Go to the [** Topics**](https://www.braintrust.dev/app/~/topics) page, expand **Automation settings**, and set **Scope** to ** Group**.
* **Group by**: Field path that identifies the group, for example `metadata.session_id`. Must resolve to a subfield under `metadata.*` or `span_attributes.*`.
* **Apply to**: When the classification is written.
* **First trace in group**: Wait for the group to fall idle, then classify it once. The classification is written to the first trace in the group. Best for completed sessions or batch analysis.
* **Every trace in group**: Classify each trace as it arrives, using all prior traces in the group as context. Best for active sessions where you want classifications to update live.
* **Group interval**: Maximum time range for a group (default: `1d`). Accepts values like `7d`, `6h`, `30m`, `86400s`.
* **Maximum traces**: Number of traces per group included in classification. Defaults to 64, which is also the maximum. Sessions longer than 64 traces are truncated to the most recent 64.
Click **Save** to apply changes.
Grouping requires data plane v2.2.1 or later and the Topics automation must be enabled.
## Adjust automation
Tune which traces are processed and how often the pipeline runs.
At high trace volume, a sampling rate as low as 5% often produces enough signal for meaningful topic clusters. Lower-volume projects benefit from keeping the rate higher so the 100-summary threshold for topic generation is met sooner.
Go to the [** Topics**](https://www.braintrust.dev/app/~/topics) page and expand **Automation settings** in the status panel.
* **Filter**: Restricts which traces are processed. Use the basic filter UI or enter a SQL expression directly. The filter matches if any span in the trace satisfies the condition, so `metadata.env = 'prod'` selects a trace when at least one of its spans has that metadata. See [Match traces across spans](/observe/filter#match-traces-across-spans) for details.
* **Sampling rate**: Percentage of incoming traces that get processed (default: 100%).
* **Idle time**: Seconds after the last trace before the automation is run again (default: 600).
* **Scope**: Whether to classify each trace independently or group related traces and classify them as a single unit. See [Group traces into conversations](#group-traces-into-conversations).
* **Advanced > Facet model**: Model used to generate facet summaries for all facets in this automation. See [Models and data handling](/observe/topics#models-and-data-handling) for details on what these models do.
* **Pause/resume**: Stop processing new logs, then resume where the automation left off. See [Pause/resume automation](#pause-resume-automation).
Click **Save** to apply changes.
You can also reach these fields from **Settings** > [** Automations**](https://www.braintrust.dev/app/~/configuration/automations) by editing the **Topics** rule.
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config set --sampling-rate 50
bt topics config set --idle-time 300
bt topics config set --filter "span_type = 'llm'"
bt topics config set --clear-filter
```
See [`bt topics config set`](/reference/cli/topics#bt-topics-config-set) for all flags.
## Tune clustering settings
Each facet has its own clustering settings that control how its summaries are grouped into topics: how many traces are sampled, which algorithm is used, and whether topic names carry over between runs. Adjust these per facet to improve topic quality.
Go to the [** Topics**](https://www.braintrust.dev/app/~/topics) page, open the ellipsis menu on a facet card, and select ** Edit clustering settings** to open the **Clustering settings** panel.
* **Max sample size**: Maximum number of traces to sample for cluster generation.
* **Hierarchy threshold**: Nest topics into parent groups once there are more topics than this threshold. Leave blank for a flat list.
* **Reconcile with previous version**: Preserve topic names through re-generation and add only genuinely new topics.
Expand **Advanced** for additional controls:
* **Clustering algorithm**: Choose **HDBSCAN (density-based)** or **K-Means**.
* For **K-Means**, set **Number of clusters** (the exact number of topics to split traces into). Leave blank for **Auto**.
* For **HDBSCAN**, set **Min cluster size** (smallest number of traces that can form its own topic) and **Min samples** (a higher value leaves more loosely-related traces without a topic).
* **Dimension reduction**: Compresses high-dimensional embeddings into fewer dimensions before clustering. Choose **UMAP**, **PCA**, or **None**.
Click **Save** to apply changes. Changes take effect the next time topics are generated, so [re-generate topics](#re-generate-topics) to apply them now.
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config topic-map set my-facet --algorithm kmeans --n-clusters 10
bt topics config topic-map set my-facet --sample-size 5000 --hierarchy-threshold 20
bt topics config topic-map set my-facet --disable-reconciliation false
```
See [`bt topics config topic-map set`](/reference/cli/topics#bt-topics-config-topic-map-set) for all flags.
Pause/resume automation
Pause the Topics automation to stop processing new logs, for example while you tune facets or manage usage. Resume it when you're ready, and processing picks up where it left off without reprocessing what was already classified. Pausing or resuming may take about 15 minutes to take effect.
Go to the [** Topics**](https://www.braintrust.dev/app/~/topics) page and expand **Automation settings** in the status panel.
* Click **Pause** to stop processing new logs.
* Click **Resume** to begin processing new logs again from where they left off.
This is a manual pause that you can reverse at any time. It's distinct from the involuntary pause that occurs when you exhaust your Topics credit. See [Common issues](#common-issues) for that case.
You can also pause and resume from **Settings** > [** Automations**](https://www.braintrust.dev/app/~/configuration/automations) by editing the **Topics** rule.
Pause and resume requires data plane v2.2.1 or later.
## Process existing traces
Process existing traces to fill coverage gaps for logs that weren't classified the first time, for example after raising the sampling rate. Traces that have already been processed are skipped.
1. Go to the [** Topics**](https://www.braintrust.dev/app/~/topics) page.
2. In the status panel, click the ellipsis menu next to ** Re-generate topics** and select **Process existing traces**.
3. Choose a time range and confirm.
Processing a large window can be costly. Start with a narrow time range when possible.
To force recomputation of facets and topics for a window, for example after changing a facet prompt, use [Rewind history](#rewind-history) instead.
## Rewind history
`bt topics rewind` replays a window of historical traces through the Topics pipeline, recomputing facet summaries and classifications for all matching traces on the next executor pass. There is no UI equivalent for this operation.
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics rewind 7d # reprocess the last 7 days
bt topics rewind 1h # reprocess the last hour
```
See [`bt topics rewind`](/reference/cli/topics#bt-topics-rewind) for all flags.
This is useful after [editing a custom facet](/observe/topics/custom-facets#manage-facets) or changing the [automation filter](#adjust-automation). Rewind the affected window so existing traces pick up the new classifications without waiting for the daily cycle.
## Common issues
Topics run on a daily cycle, so new classifications won't appear immediately after enabling. See [Check automation status](#check-automation-status) to see where the pipeline is. If you want results sooner, [re-generate topics](#re-generate-topics) to trigger a run immediately.
Topic generation requires at least 100 facet summaries. If the [automation status](#check-automation-status) shows **Waiting for facets**, more traces need to be processed first.
* [Increase the sampling rate](#adjust-automation) to process traces faster.
* If the project has few traces, wait for more to arrive.
* On the [** Topics**](https://www.braintrust.dev/app/~/topics) page, open the **View logs with \[facet]** menu on a facet card and select **View matched logs** to confirm the facet is producing usable summaries, or **View processed logs** to confirm it's running at all.
Classification runs automatically after topics are generated. Check the [automation status](#check-automation-status):
* **Processing logs**: Classification is in progress. Wait for it to complete.
* **Idle**: [Re-generate topics](#re-generate-topics) to trigger a new cycle.
* **Older logs**: Only approximately the most recent 500 logs are backfilled on enable. Traces outside that window won't have classifications.
By default, Topics classifies each trace independently. When a conversation spans multiple traces (typical with auto-instrumentation), turns can land in different topics or sentiments. [Group traces into conversations](#group-traces-into-conversations) so Topics classifies the group as a whole.
On the Starter plan without on-demand usage, Topics is paused once you exhaust your monthly Topics credit, and the automation can't be unpaused until you add a card or the credit resets on the next billing cycle. [Add a card](/admin/billing/change-plan#enable-on-demand-usage) to resume Topics at the overage rates. See [What happens when I run out of Topics credit?](/admin/billing/faq#what-happens-when-i-run-out-of-topics-credit) for details.
This is different from a [manual pause](#pause-resume-automation), which you choose and can resume at any time.
## Next steps
* [Build datasets](/observe/topics/act-on-findings#build-datasets-from-topics) from logs once classifications are fresh.
* [`bt topics`](/reference/cli/topics) full CLI reference.