# Segment User V2
**Action ID:** `segment_user_v2`
## Description
Segment user V2
## Input Parameters
| Name | Type | Required | Default | Description |
| ----- | ------ | :------: | ------- | --------------------------------------------------------------------- |
| users | string | ✓ | - | List of users in JSON format. Should be a JSON array of user objects. |
View JSON Schema
```json
{
"description": "Segment user",
"properties": {
"users": {
"description": "List of users in JSON format.",
"title": "List of Users",
"type": "string"
}
},
"required": [
"users"
],
"title": "SegmentUserV2NodeInput",
"type": "object"
}
```
## Output Parameters
| Name | Type | Description |
| -------- | ----- | ----------------------------------------------------------------------------- |
| segments | array | User segments with categorized user groups using enhanced segmentation logic. |
View JSON Schema
```json
{
"description": "Segment user output",
"properties": {
"segments": {
"description": "User segments.",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "User Segments",
"type": "array"
}
},
"required": [
"segments"
],
"title": "SegmentUserV2NodeOutput",
"type": "object"
}
```
## How It Works
This is an enhanced version of the user segmentation node with improved algorithms and capabilities. It analyzes user data with advanced segmentation logic, providing more granular and accurate user groupings. The V2 version includes better handling of edge cases, more sophisticated pattern recognition, and enhanced segment quality. It processes the user list and returns optimized segments with detailed characteristics for each group.
## Usage Examples
### Example 1: Advanced Behavioral Segmentation
**Input:**
```
users: '[
{"id": 1, "name": "Alex", "last_login": "2024-01-14", "session_count": 120, "avg_session_time": 45, "feature_adoption": 0.85},
{"id": 2, "name": "Beth", "last_login": "2023-12-01", "session_count": 5, "avg_session_time": 10, "feature_adoption": 0.20},
{"id": 3, "name": "Chris", "last_login": "2024-01-13", "session_count": 80, "avg_session_time": 35, "feature_adoption": 0.70},
{"id": 4, "name": "Dana", "last_login": "2024-01-15", "session_count": 200, "avg_session_time": 60, "feature_adoption": 0.95}
]'
```
**Output:**
```
segments: [
{
"segment_name": "Champions",
"description": "Highly engaged users with strong feature adoption",
"count": 2,
"characteristics": {"avg_sessions": 160, "avg_feature_adoption": 0.90},
"users": [
{"id": 1, "name": "Alex", "engagement_score": 92},
{"id": 4, "name": "Dana", "engagement_score": 98}
]
},
{
"segment_name": "Promising",
"description": "Active users with growth potential",
"count": 1,
"characteristics": {"avg_sessions": 80, "avg_feature_adoption": 0.70},
"users": [{"id": 3, "name": "Chris", "engagement_score": 75}]
},
{
"segment_name": "At Risk",
"description": "Low engagement users requiring attention",
"count": 1,
"characteristics": {"avg_sessions": 5, "avg_feature_adoption": 0.20},
"users": [{"id": 2, "name": "Beth", "engagement_score": 25}]
}
]
```
### Example 2: Revenue-Based Segmentation
**Input:**
```
users: '[
{"id": 501, "email": "vip@example.com", "lifetime_value": 15000, "avg_order": 500, "frequency": "weekly"},
{"id": 502, "email": "regular@example.com", "lifetime_value": 2400, "avg_order": 120, "frequency": "monthly"},
{"id": 503, "email": "occasional@example.com", "lifetime_value": 350, "avg_order": 70, "frequency": "rarely"}
]'
```
**Output:**
```
segments: [
{
"segment_name": "Platinum Tier",
"description": "Top revenue generators",
"count": 1,
"total_value": 15000,
"users": [{"id": 501, "email": "vip@example.com", "tier": "platinum"}]
},
{
"segment_name": "Gold Tier",
"description": "Consistent mid-value customers",
"count": 1,
"total_value": 2400,
"users": [{"id": 502, "email": "regular@example.com", "tier": "gold"}]
},
{
"segment_name": "Bronze Tier",
"description": "Low-value occasional customers",
"count": 1,
"total_value": 350,
"users": [{"id": 503, "email": "occasional@example.com", "tier": "bronze"}]
}
]
```
### Example 3: Multi-Dimensional Segmentation
**Input:**
```
users: '[
{"id": 701, "age": 28, "location": "urban", "device": "mobile", "plan": "premium", "satisfaction": 4.5},
{"id": 702, "age": 45, "location": "suburban", "device": "desktop", "plan": "free", "satisfaction": 3.2},
{"id": 703, "age": 32, "location": "urban", "device": "mobile", "plan": "premium", "satisfaction": 4.8}
]'
```
**Output:**
```
segments: [
{
"segment_name": "Premium Mobile Urban",
"description": "High-satisfaction urban premium mobile users",
"count": 2,
"avg_satisfaction": 4.65,
"users": [
{"id": 701, "profile": "young_professional"},
{"id": 703, "profile": "young_professional"}
]
},
{
"segment_name": "Free Desktop Suburban",
"description": "Moderate-satisfaction suburban desktop users",
"count": 1,
"avg_satisfaction": 3.2,
"users": [{"id": 702, "profile": "mature_user"}]
}
]
```
## Common Use Cases
* **Advanced Customer Lifecycle Management**: Segment users across complex lifecycle stages with multiple factors
* **Predictive Churn Analysis**: Identify at-risk segments using sophisticated behavioral patterns
* **Personalized Engagement Strategies**: Create highly targeted campaigns based on multi-dimensional segments
* **Product Development Insights**: Understand user segments to guide feature prioritization
* **Revenue Optimization**: Identify high-value segments and optimize monetization strategies
* **Customer Success Programs**: Allocate resources efficiently based on detailed segment characteristics
* **Cross-sell and Upsell**: Target specific segments with relevant product recommendations
## Error Handling
| Error Type | Cause | Solution |
| ------------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
| Invalid JSON Format | Users parameter contains malformed JSON | Validate JSON syntax and ensure proper formatting |
| Empty User Array | No users provided in the array | Include at least one user object for segmentation |
| Insufficient Data | User objects lack enough attributes for meaningful segmentation | Provide richer user data with multiple attributes |
| Data Type Mismatch | User attributes have incorrect data types | Ensure numeric fields are numbers, strings are text, etc. |
| Segmentation Error | Advanced algorithm cannot process the data | Verify data quality and consistency across user objects |
| Memory Limit | Too many users to process | Consider batching large user lists into smaller groups |
## Notes
* **Version 2 Enhancements**: This version includes improved segmentation algorithms, better pattern recognition, and more detailed segment metadata compared to V1.
* **Multi-Dimensional Analysis**: V2 can analyze multiple user attributes simultaneously for more sophisticated segmentation.
* **Segment Quality**: Enhanced algorithms produce higher quality segments with clearer distinctions and more actionable insights.
* **Performance**: While more sophisticated, V2 maintains good performance even with larger user datasets.
* **Rich Metadata**: Segments include additional information like characteristics, scores, and descriptions for better understanding.
* **Backward Compatibility**: Output format is compatible with V1, with additional optional fields for enhanced functionality.
* **Best Practices**: Provide comprehensive user data including behavioral, demographic, and transactional attributes for optimal segmentation results.
* **Use Case Selection**: Use V2 when you need more nuanced segmentation compared to the basic V1 implementation.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.agenticflow.ai/reference/nodes/segment_user_v2.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.