Auto-Segmentation

​

Overview

Auto-Segmentation analyzes your schema data to discover natural customer segments. Instead of manually defining segments based on assumptions, you select a schema and the AI identifies clusters of customers with similar characteristics. Navigate to AI > Segments in the sidebar to view the segment insights dashboard, or trigger analysis programmatically via POST /api/v1/ai/analyze/{type} with type=segments in the path and a schemaId in the request body. The Segments dashboard page (/ai/segments) automatically runs a health check and extracts segment-related findings. It shows segment data health status and overall segmentation readiness, refreshing every 5 minutes.

​

How It Works

​

Dual-Tier Analysis

The ML Worker tier is more accurate because it processes the entire dataset and uses statistical validation (silhouette score) to find the natural number of clusters rather than relying on pattern matching.

​

Heuristic Fallback

If the LLM call fails, the system falls back to a deterministic heuristic segmentation:

1. Finds the numeric field with the widest range (max - min)
2. Splits into three segments at the 33rd and 67th percentiles: Low, Mid, and High
3. Each segment gets filter rules, characteristics, and suggested marketing use cases

If no numeric fields exist, a single “All Customers” segment is returned with a message suggesting you add numeric attributes.

​

Segment Card Format

Each segment card (a segment-result object) displays: Example card:

High-Value Loyalists — 2,340 customers (18%)

• Average spend: $1,250 (vs.$480 population avg)
• Average tenure: 4.2 years (vs. 1.8 population avg)
• Primary channel: Email (72%)
• Suggested: Premium offers, loyalty rewards, lower contact frequency

​

Generating Segments from the UI

On AI > Segments, pick a schema and click Generate segments. The analyzer runs (POST /api/v1/ai/analyze/segments) and every proposed segment is persisted as a recommendation (deduplicated against open ones) and shown in the Segment Recommendations inbox on the same page — and in the unified inbox on AI Insights. If the ml-router flags the dataset as expensive, you’ll see a cost warning with a Run anyway confirmation first.

​

Applying Segments

Clicking Apply on a segment recommendation (two-step confirm, admin only) creates a draft AI Customer Segment carrying the full definition — name, filter rules, size estimate, characteristics, and suggested use. Draft segments are never auto-activated; review them before use.

​

Field Selection Tips

• Numeric fields work best — Income, age, spend, tenure, and score fields produce clearer clusters
• Limit categorical fields — High-cardinality categoricals (e.g., zip code) add noise. Prefer broad categories like region or account type
• Exclude IDs — Do not include customer_id, email, or other unique identifiers as segmentation fields
• Include behavioral data — If you have interaction summaries (total_clicks, avg_response_rate), include them for behaviorally meaningful segments

​

Advanced Parameters

Each segmentation run can be fine-tuned using the Advanced Parameters panel on the segmentation page. Expand the panel to adjust: Per-run overrides do not change your saved tenant configuration. To change the organization-wide defaults, go to AI Configuration.

​

Large Dataset Warning

When the selected schema contains 5,000 or more rows, a confirmation dialog appears before analysis begins. The dialog shows:

• Accuracy comparison — ML Worker uses K-Means with silhouette scoring on the full dataset vs. LLM analysis of field statistics
• Estimated cost — Token count and approximate cost if proceeding with LLM
• Speed comparison — ML Worker processes locally in seconds vs. LLM round-trip

You can choose Use ML Worker (recommended for large datasets) or Proceed with LLM (uses field statistics summary).

​

Next Steps