Skip to main content

​
Overview

Turret automatically detects which metadata fields are categorical (enums) and makes them available for segmentation. This lets you filter your dashboard and journey views by attributes like platform, language, user plan, or any other categorical metadata you send.

​
How It Works

When you send events with metadata, Turret analyzes each field and classifies it as one of three types:
TypeDescriptionExampleSegmentable
textFree-form text contentUser prompts, messagesNo
enumCategorical values with limited optionsplatform: "ios", language: "spanish"Yes
numberNumeric valuesResponse time, token countNo

​
Automatic Detection

Turret uses an LLM to intelligently classify your metadata fields:
  1. First event: When you send an event with new metadata keys, Turret analyzes the field names and sample values
  2. Classification: Fields are classified as text, enum, or number based on context
  3. Re-validation: After 100 events, classifications are re-validated with real sample values to ensure accuracy
Classification happens automatically in the background. You don’t need to configure anything - just send your events with metadata and Turret handles the rest.

​
Using Segments

​
In the Dashboard

  1. Click the Segments button in the top-right toolbar
  2. A side panel opens showing all detected enum fields
  3. Select a value to filter the view (e.g., platform: ios)
  4. Click Apply filters to update the dashboard
The dashboard will now show only topics matching your selected segments.

​
In Journeys

Segments work the same way in the Journeys view:
  1. Click Segments to open the filter panel
  2. Select values for any enum fields
  3. Apply to see journey patterns for that segment
This is powerful for understanding how different user segments behave differently. For example:
  • Do iOS users ask different questions than Android users?
  • Do Spanish-speaking users have different journey patterns?
  • Do Pro plan users have different needs than Free users?

​
Sending Segmentable Metadata

Include categorical metadata in your events: 
await fetch('https://api.useturret.com/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    name: 'user_message',
    session_id: sessionId,
    user_id: userId,
    metadata: {
      prompt: userMessage,        // text - for clustering
      platform: 'ios',            // enum - for segmentation
      language: 'spanish',        // enum - for segmentation
      user_plan: 'pro'            // enum - for segmentation
    }
  })
});

​
Good Segmentation Fields

Platform & Device

  • platform: “ios”, “android”, “web”
  • device_type: “mobile”, “tablet”, “desktop”
  • browser: “chrome”, “safari”, “firefox”

User Attributes

  • user_plan: “free”, “pro”, “enterprise”
  • user_type: “new”, “returning”, “power_user”
  • account_age: “trial”, “active”, “churned”

Locale & Region

  • language: “english”, “spanish”, “french”
  • country: “US”, “UK”, “DE”
  • timezone: “PST”, “EST”, “UTC”

Context

  • feature: “chat”, “search”, “analytics”
  • source: “web_app”, “mobile_app”, “api”
  • environment: “production”, “staging”

​
Overriding Field Types

Sometimes Turret’s automatic detection may classify a field differently than you intend. You can override the detected type in Settings.

​
Accessing Override Settings

  1. Go to Settings in your dashboard
  2. Click the Metadata tab
  3. Find the field you want to override
  4. Click the type dropdown and select the correct type
  5. Click Save

​
When to Override

If a field like conversation_id has limited values during early usage, it might be detected as an enum. Override it to text since IDs are identifiers, not categories.
If a field like status contains values like “pending”, “complete”, “failed” but was detected as text, override it to enum to enable segmentation.
If a field like response_time_ms was detected as text because values were sent as strings, override it to number for proper handling.

​
Override Behavior

  • Immediate effect: Overrides take effect immediately for dashboard filtering
  • Persistent: Overrides are saved and won’t be changed by re-validation
  • Reversible: Click “Clear” next to an override to return to auto-detection
Overriding a field from enum to text will remove it from the Segments panel. Make sure this is intended.

​
Best Practices

​
Keep Enum Values Consistent

Use consistent values for categorical fields: 
// Good - consistent values
metadata: { platform: 'ios' }
metadata: { platform: 'android' }
metadata: { platform: 'web' }

// Bad - inconsistent casing/naming
metadata: { platform: 'iOS' }
metadata: { platform: 'Android' }
metadata: { platform: 'Web App' }

​
Limit Enum Cardinality

Fields with too many unique values aren’t useful for segmentation: 
// Good - limited distinct values
metadata: { user_plan: 'free' }  // ~3-5 distinct values

// Bad - too many distinct values
metadata: { user_email: 'user@example.com' }  // Thousands of values

​
Use Meaningful Field Names

Clear field names help with automatic detection: 
// Good - clear field names
metadata: {
  platform: 'ios',
  detected_language: 'spanish',
  subscription_tier: 'pro'
}

// Less clear - ambiguous names
metadata: {
  p: 'ios',
  lang: 'spanish',
  tier: 'pro'
}

​
Combining Segments with Journeys

Segments are most powerful when combined with journey analysis:
  1. Filter by segment: Select platform: ios in the Segments panel
  2. View journeys: See how iOS users flow through topics
  3. Compare segments: Switch to platform: android and compare patterns
  4. Identify differences: Discover segment-specific pain points or opportunities
Try filtering by user plan to see if free users have different journey patterns than paid users. This can reveal upsell opportunities or friction points in your upgrade flow.