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

# Topics

> Automatically categorize conversations by subject matter

## What are Topics?

Topics are subjects that users discuss in their conversations with your AI. Thunder automatically detects and categorizes topics from message content, helping you understand what your users care about most.

Examples of topics:

* "Password Reset"
* "Billing Questions"
* "Product Features"
* "Technical Support"

## How Topics are Detected

Thunder analyzes message content using AI models to identify the subjects being discussed. When similar subjects appear across multiple conversations, they're grouped into topics.

Topic detection improves over time - as Thunder sees more conversations from your instance, topic categorization becomes more accurate and specific.

## Topic Metrics

Query topics to understand their prevalence and user sentiment:

| Metric     | Description                                               |
| ---------- | --------------------------------------------------------- |
| `sessions` | Number of conversations that discussed this topic         |
| `users`    | Unique users who discussed this topic                     |
| `messages` | Total messages related to this topic                      |
| `sat`      | Satisfaction signals in conversations about this topic    |
| `dsat`     | Dissatisfaction signals in conversations about this topic |
| `netSat`   | Net satisfaction score                                    |

## Querying Topics

Get your most-discussed topics:

```bash theme={null}
curl "https://api.usethunder.com/v1/query?\
groupBy=TOPIC&\
instanceId=your-instance-id&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=ALL&\
fields=sessions,users,messages,sat,dsat&\
sort.field=sessions&\
sort.order=DESC" \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "elements": [
    {
      "dimensions": {
        "topic": {
          "id": "topic-uuid",
          "name": "Billing Questions",
          "clusterId": null
        }
      },
      "fields": {
        "sessions": 342,
        "users": 289,
        "messages": 1024,
        "sat": 45,
        "dsat": 12
      }
    }
  ],
  "pagination": { "total": 47, "limit": 50, "offset": 0 }
}
```

## Time-Series Analysis

Track topic trends over time using `timeGranularity`:

```bash theme={null}
curl "https://api.usethunder.com/v1/query?\
groupBy=TOPIC&\
instanceId=your-instance-id&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=DAY&\
fields=sessions,messages" \
  -H "x-api-key: YOUR_API_KEY"
```

This returns one row per topic per day, letting you see how topic volume changes over time.

## Filtering Sessions by Topic

Find all sessions that discussed a specific topic:

```bash theme={null}
curl "https://api.usethunder.com/v1/query?\
groupBy=SESSION&\
instanceId=your-instance-id&\
topicIds=topic-uuid-here&\
dateRange.start=2024-01-01T00:00:00Z&\
dateRange.end=2024-01-31T23:59:59Z&\
timeGranularity=ALL&\
fields=messages,sat,dsat&\
dimensionFields=title,summary" \
  -H "x-api-key: YOUR_API_KEY"
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Identify Hot Topics" icon="fire">
    Sort by session count to find what users ask about most. Prioritize documentation and training for high-volume topics.
  </Card>

  <Card title="Find Problem Areas" icon="triangle-exclamation">
    Filter for topics with high DSAT. These are subjects where your AI may need improvement.
  </Card>

  <Card title="Track Trends" icon="chart-line">
    Use time-series queries to spot emerging topics or declining interest.
  </Card>

  <Card title="Content Planning" icon="lightbulb">
    Use topic data to guide knowledge base updates and AI training priorities.
  </Card>
</CardGroup>

***

See [Querying Metrics](/guides/querying-metrics) for more query patterns and the full field reference.