> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Topics grouping and span scope

> Configure Topics grouping keys to get separate facet results for distinct session stretches, and understand the difference between Trace, Group, and span scope.

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Any
> * Deployment - Any
> * Data plane - v2.2.1 or later for Group scope
> * Use case - How to group traces for Topics classification by session stretch and use Trace or Group scope.

## Summary

To get separate facet results for session stretches, log each stretch as a separate trace or group turn-based traces using a distinct key for each stretch.

## What is happening

Topics offers **Trace** and **Group** scopes. Topics does not support span-level scope. With **Trace** scope, a session logged as a single trace is one item to classify. With **Group** scope, related traces are classified as one unit, so grouping by session combines traces rather than separating stretches.

## Fix or suggestion

### Option 1: Use a distinct grouping key for each stretch

1. Emit a consistent grouping key on each turn-based trace in a stretch. Use a distinct value for each stretch.
2. In [** Topics**](https://www.braintrust.dev/app/~/topics), set **Scope** to **Group** and configure **Group by** to use the key you log.
3. Choose **First trace in group** or **Every trace in group** to control when Topics classifies traces and where it writes the results.

Implications:

* **First trace in group** waits for the group to become idle and writes its classification to the first trace.
* **Every trace in group** classifies each arriving trace using prior traces in the group as context. Those classifications can differ.

### Option 2: Produce smaller traces or attach group keys after the fact

1. Emit one trace for each stretch you want classified and set **Scope** to **Trace** so each stretch is classified independently.
2. For retrospective grouping, assign one consistent segmentation key per separate trace, with a distinct value for each stretch. Set **Scope** to **Group** and configure **Group by** to use that key.
3. Use a custom facet prompt to focus extraction within the configured scope.

Example trace metadata for retrospective grouping (Group scope):

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "trace_id": "abc123",
  "metadata": {
    "session_id": "s-1234",
    "conversation_id": "conv-1"
  }
}
```

## How to confirm it worked

* Check [** Topics**](https://www.braintrust.dev/app/~/topics) for a separate facet result for each stretch.
* For **Group** scope, confirm classifications follow the **First trace in group** or **Every trace in group** behavior you selected.

## Notes

* Topics runs as a batched classification pipeline. Topic generation requires at least 100 facet summaries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.