Segments

Create reusable user groups to simplify targeting across multiple flags.

Overview

Segments are reusable definitions of user groups. Instead of duplicating the same targeting conditions across multiple flags, define a segment once and reference it everywhere.

Benefits

DRY principle - Define targeting rules once, use everywhere
Easier maintenance - Update a segment, all flags using it update automatically
Consistency - Ensure the same users are targeted across features
List-based targeting - Import specific user IDs for precise control

Segment Types

Rule-Based Segments

Define segments using conditions (like targeting rules). Users are evaluated dynamically based on their attributes.

Example: "Beta Testers"

Conditions:
• beta_tester = true
OR
• email ends_with @company.com

List-Based Segments

Explicitly list user IDs. Perfect for VIP users, specific accounts, or imported lists.

Example: "Enterprise Customers"

User IDs:
• user-001
• user-002
• user-003

Creating Segments

Rule-Based Segment

POST /api/v1/projects/:projectId/segments

{
  "name": "Beta Testers",
  "description": "Users opted into beta program",
  "segment_type": "rule_based",
  "conditions": [
    {
      "attribute": "beta_tester",
      "operator": "equals",
      "value": "true"
    }
  ]
}

List-Based Segment

POST /api/v1/projects/:projectId/segments

{
  "name": "Enterprise Customers",
  "description": "Large accounts with custom contracts",
  "segment_type": "list_based"
}

// Then add users to the segment
POST /api/v1/projects/:projectId/segments/:segmentId/users
{
  "user_ids": ["user-001", "user-002", "user-003"]
}

Using Segments in Targeting Rules

When creating a targeting rule, you can reference a segment instead of defining inline conditions:

Flag targeting rule with segment

{
  "rules": [
    {
      "name": "Beta users get new feature",
      "segment_id": "550e8400-e29b-41d4-a716-446655440000",
      "rollout": 100,
      "enabled": true
    }
  ]
}

Tip: You can mix segment-based rules with inline condition rules in the same flag. Rules are still evaluated top-to-bottom, first match wins.

Bulk Import Users

For list-based segments, you can import users in bulk via the dashboard or API:

Bulk add users

POST /api/v1/projects/:projectId/segments/:segmentId/users
{
  "user_ids": [
    "user-001",
    "user-002",
    "user-003",
    // ... up to 10,000 users per request
  ]
}

In the dashboard, you can paste a comma-separated or newline-separated list of user IDs.

Managing Segment Users

Action	Endpoint
List users in segment	GET /segments/:segmentId/users
Add users to segment	POST /segments/:segmentId/users
Remove users from segment	DELETE /segments/:segmentId/users

Best Practices

Use descriptive names

Name segments by what they represent, not how they're used. "Enterprise Customers" is better than "Users for Premium Feature".

Prefer rule-based for dynamic groups

Use rule-based segments when membership is determined by user attributes. Use list-based when you need explicit control over exactly which users are included.

Document your segments

Use the description field to explain the purpose and criteria for each segment. This helps team members understand what each segment represents.

Example Use Cases

1. Beta Program

Create a "Beta Testers" segment and use it across all experimental features. When a user joins the beta program, they automatically get access to all beta features.

// Segment: Beta Testers (rule_based)
// Condition: beta_opted_in = true

// Flag: new-editor → uses "Beta Testers" segment
// Flag: ai-assistant → uses "Beta Testers" segment
// Flag: dark-mode-v2 → uses "Beta Testers" segment

2. Enterprise Customers

Maintain a list of enterprise account IDs. These users get early access to features and premium support.

// Segment: Enterprise (list_based)
// Users: acme-corp, bigcorp, megainc

// Flag: advanced-analytics → 100% for Enterprise, 0% others
// Flag: sso-integration → 100% for Enterprise only

3. Regional Targeting

Create segments for different regions to comply with regulations or localize features.

// Segment: EU Users (rule_based)
// Condition: country IN "DE,FR,IT,ES,NL,..."

// Flag: gdpr-consent-banner → 100% for EU Users
// Flag: cookie-preferences → 100% for EU Users