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

# Understanding Topics & Journeys

> Learn how Turret automatically groups similar events and tracks user journeys

## What Are Topics?

Turret automatically groups your events based on semantic similarity in the metadata text. Unlike traditional analytics that only group by exact matches, Turret understands meaning and context.

It leverages the technology powering state-of-the-art LLMs and semantic clustering algorithms to detect similar keywords and phrases. We call these clusters "topics".

For example, these events would be clustered together as a "topic":

* "How do I reset my password?"
* "I forgot my login credentials"
* "Can't remember my account password"

## How Clustering Works

Turret uses advanced natural language processing to:

1. **Analyze text meaning**: Generate vector embeddings for your event metadata using an embedding model
2. **Find similarities**: Compare events based on embedding similarity, not just keywords
3. **Create clusters**: Group events that share similar meanings or patterns
4. **Label automatically**: Use an LLM to generate human-readable descriptions for each cluster (e.g., "Password Reset Requests")
5. **Update dynamically**: Clusters evolve as new events are added

<Info>
  Clustering happens automatically in the background. You don't need to configure anything - just send your events and Turret does the rest.
</Info>

## Journey Tracking

When events share the same `session_id`, Turret tracks how users flow through different topics within a conversation.

### How It Works

Consider a user conversation:

1. User asks about pricing (Cluster A)
2. User asks about features (Cluster B)
3. User asks about pricing again (Cluster A)

This creates a journey: **A → B → A**

### Journey Analytics

Turret provides insights like:

<CardGroup cols={2}>
  <Card title="Starting Topics" icon="play">
    What do users ask about first in their conversations?
  </Card>

  <Card title="Common Follow-ups" icon="arrow-right">
    After topic X, users often ask about Y
  </Card>

  <Card title="Back-and-forth Patterns" icon="arrows-left-right">
    Users bounce between topics A and B
  </Card>

  <Card title="Drop-off Points" icon="door-open">
    Where do conversations tend to end?
  </Card>
</CardGroup>

### Enabling Journey Tracking

To enable journey tracking, include `session_id` in your events:

```json theme={null}
{
  "name": "user_prompt",
  "session_id": "conv_abc123",
  "user_id": "user_456",
  "metadata": {
    "prompt": "How much does the pro plan cost?"
  }
}
```

Use whatever ID you already use to group messages in a conversation (e.g., your thread ID, conversation ID, or chat session ID).

## Types of Clusters

### Intent-Based Clusters

Groups events by what users are trying to accomplish:

<CardGroup cols={2}>
  <Card title="Authentication Issues" icon="lock">
    * "I can't log in"
    * "Password reset not working"
    * "Account locked out"
  </Card>

  <Card title="Feature Requests" icon="lightbulb">
    * "Can you add dark mode?"
    * "Would love to see templates"
    * "Need better export options"
  </Card>
</CardGroup>

### Topic-Based Clusters

Groups events by subject matter:

<CardGroup cols={2}>
  <Card title="Technical Support" icon="wrench">
    * "API not responding"
    * "Getting 500 errors"
    * "Integration failing"
  </Card>

  <Card title="Content Creation" icon="pen">
    * "Write a blog post about AI"
    * "Create marketing copy"
    * "Generate product descriptions"
  </Card>
</CardGroup>

### Sentiment-Based Topics

Groups events by emotional tone:

<CardGroup cols={2}>
  <Card title="Positive Feedback" icon="thumbs-up">
    * "This is amazing!"
    * "Love the new features"
    * "Exactly what I needed"
  </Card>

  <Card title="Frustration" icon="face-frown">
    * "This is confusing"
    * "Why isn't this working?"
    * "Too complicated"
  </Card>
</CardGroup>

## Viewing Topics in the Dashboard

Your [Turret Dashboard](https://dashboard.useturret.com) shows topics and journeys in several ways:

### Topic Overview

* **Label**: Auto-generated description of the topic
* **Size**: Number of events in each topic
* **Growth**: How topics are expanding over time
* **Trends**: Which topics are most active

### Topic Details

* **Representative events**: Key examples from each topic
* **Time series**: How topic activity changes over time
* **Metadata patterns**: Common themes in the clustered events

### Journey Insights

* **Flow diagrams**: Visual representation of how users move through topics
* **Starting topics**: What users ask about first
* **Transition patterns**: Common paths between topics
* **Session analysis**: Deep dive into individual user sessions

### Segmentation

Filter topics and journeys by categorical metadata fields:

* **Platform filtering**: Compare iOS vs Android user patterns
* **Language segments**: Analyze behavior by user language
* **Plan comparison**: See how free vs paid users differ

<Tip>
  Combine segmentation with journey analysis for powerful insights. Filter by `platform: ios` to see how iOS-specific user journeys differ from Android users. Learn more in the [Segmentation guide](/essentials/segmentation).
</Tip>

### Cluster Insights

* **Emerging patterns**: New topics that are forming
* **Anomalies**: Unusual events that don't fit existing topics
* **Correlations**: How topics relate to each other

## Interpreting Results

### High-Value Topics

Pay special attention to:

<AccordionGroup>
  <Accordion icon="chart-line" title="Fast-growing topics">
    Rapid growth indicates emerging user needs or pain points that require attention.
  </Accordion>

  <Accordion icon="triangle-exclamation" title="Problem-related topics">
    Topics containing error messages, complaints, or confusion signals areas for improvement.
  </Accordion>

  <Accordion icon="star" title="Feature request topics">
    Groups of similar requests help prioritize product development.
  </Accordion>

  <Accordion icon="heart" title="Positive feedback topics">
    Understand what users love most about your product.
  </Accordion>
</AccordionGroup>

### Using Journeys for Product Decisions

#### Identify Drop-off Points

```
Journey Pattern: Pricing → Features → [END]
Insight: Users leave after viewing features
Action: Improve feature page content or add clearer CTAs
```

#### Optimize Onboarding

```
Journey Pattern: Setup → Error → Setup → Error → [END]
Insight: Users stuck in setup loop
Action: Improve setup documentation or UX
```

#### Understand User Intent

```
Journey Pattern: Pricing → Comparison → Pricing → Purchase
Insight: Users need comparison info before buying
Action: Make comparison content more accessible
```

### Using Topics for Product Decisions

#### Feature Prioritization

```
Topic: "Advanced filtering options"
- Size: 247 events
- Growth: +45% this week
- Action: High priority for next sprint
```

#### Content Strategy

```
Topic: "How to integrate with Slack"
- Size: 89 events
- Pattern: Users need integration help
- Action: Create detailed integration guide
```

#### UX Improvements

```
Topic: "Can't find the export button"
- Size: 156 events
- Pattern: UI confusion
- Action: Redesign export workflow
```

## Best Practices for Analysis

### Regular Review

* Check your dashboard weekly to spot new trends
* Identify user behaviors that you expect and don't expect
* Monitor topic health and diversity
* Review journey patterns for optimization opportunities

### Cross-Reference with Metrics

* Compare topic activity with business metrics
* Look for correlations between topics and user retention
* Track how addressing topic insights affects user satisfaction
* Analyze how journey patterns correlate with conversion

### Team Collaboration

* Share topic insights with product, engineering, and customer success teams
* Use topics and journeys to inform sprint planning and roadmap decisions
* Create feedback loops between analysis and product development

<Tip>
  The most actionable insights often come from combining topic analysis with journey patterns. Understanding not just what users ask about, but how they progress through topics, reveals powerful optimization opportunities.
</Tip>