Segments

Create and save powerful filter combinations to analyze specific user groups and behavior patterns.

Overview

Segments allow you to define reusable filters that identify specific subsets of your users or events. Instead of manually configuring filters each time, save them as segments for quick access and consistent analysis.

Use Cases

• Geographic Analysis: Users from specific countries or cities
• Traffic Sources: Users from organic search, paid ads, or referrals
• Device Targeting: Mobile vs desktop users
• Campaign Performance: Users from specific UTM campaigns
• Browser Compatibility: Users on specific browsers
• High-Value Users: Users with revenue above a threshold

Creating a Segment

Via UI

1. Navigate to Segments in the sidebar
2. Click Create Segment
3. Enter a name and optional description
4. Add filters:
   • Click Add Filter
   • Select a field (country, browser, UTM source, etc.)
   • Choose an operator (equals, contains, starts with, etc.)
   • Enter a value
5. Add multiple filters to refine your segment
6. Click Create Segment

Via API

POST /api/segments
{
  "projectId": "your-project-id",
  "name": "US Mobile Users",
  "description": "Mobile users from the United States",
  "filters": [
    {
      "field": "country",
      "operator": "equals",
      "value": "US"
    },
    {
      "field": "device",
      "operator": "equals",
      "value": "mobile"
    }
  ]
}

Available Filters

Geographic Filters

• country: Country code (e.g., "US", "GB", "FR")
• city: City name

Technology Filters

• browser: Browser name (Chrome, Firefox, Safari, etc.)
• os: Operating system (Windows, macOS, iOS, Android, etc.)
• device: Device type (desktop, mobile, tablet)
• language: Browser language (en-US, es, fr, etc.)

Traffic Source Filters

• utm_source: Traffic source (google, facebook, newsletter, etc.)
• utm_medium: Traffic medium (cpc, email, social, etc.)
• utm_campaign: Campaign name
• utm_content: Ad content or variant
• utm_term: Paid search keywords
• referrer: Referring URL

Event Filters

• eventName: Name of the event
• userId: User identifier
• sessionId: Session identifier

Revenue Filters

• revenueAmount: Transaction amount (numeric comparison)
• revenueCurrency: Currency code (USD, EUR, GBP, etc.)

Filter Operators

Text Operators

• equals: Exact match (case-sensitive)
• not_equals: Does not match
• contains: Contains substring
• not_contains: Does not contain substring
• starts_with: Starts with prefix
• ends_with: Ends with suffix

Numeric Operators

• equals: Equal to value
• not_equals: Not equal to value
• greater_than: Greater than value
• less_than: Less than value
• greater_than_or_equal: Greater than or equal to value
• less_than_or_equal: Less than or equal to value

Example Segments

High-Value Customers

{
  "name": "High-Value Customers",
  "filters": [
    {
      "field": "revenueAmount",
      "operator": "greater_than",
      "value": 100
    }
  ]
}

Google Ads Traffic

{
  "name": "Google Ads Traffic",
  "filters": [
    {
      "field": "utm_source",
      "operator": "equals",
      "value": "google"
    },
    {
      "field": "utm_medium",
      "operator": "equals",
      "value": "cpc"
    }
  ]
}

Mobile Users from Europe

{
  "name": "European Mobile Users",
  "filters": [
    {
      "field": "device",
      "operator": "equals",
      "value": "mobile"
    },
    {
      "field": "country",
      "operator": "in",
      "value": ["GB", "FR", "DE", "IT", "ES"]
    }
  ]
}

Using Segments

In Dashboards

Apply segments to dashboard widgets to view metrics for specific user groups. This helps you compare performance across different audiences.

In Reports

Filter event lists and analytics reports by segment to focus on relevant data. Segments persist across sessions for consistent analysis.

In Goals

Track goal completions for specific segments to measure conversion rates across different user groups.

API Reference

List Segments

GET /api/segments?projectId={projectId}

Response:
{
  "segments": [
    {
      "id": "seg_123",
      "name": "US Mobile Users",
      "description": "Mobile users from the United States",
      "filters": [...],
      "createdAt": "2025-12-05T...",
      "updatedAt": "2025-12-05T..."
    }
  ]
}

Get Segment

GET /api/segments/{segmentId}

Response:
{
  "segment": {
    "id": "seg_123",
    "projectId": "proj_123",
    "name": "US Mobile Users",
    "description": "...",
    "filters": [...]
  }
}

Update Segment

PATCH /api/segments/{segmentId}
{
  "name": "Updated Name",
  "filters": [...]
}

Delete Segment

DELETE /api/segments/{segmentId}

Best Practices

Naming Conventions

• Use descriptive names that clearly identify the segment
• Include key attributes: "US Mobile Users", "High-Value Customers"
• Avoid overly technical names if sharing with non-technical stakeholders

Filter Strategy

• Start broad and add filters to narrow down
• Combine geographic and behavioral filters for deeper insights
• Test segments with sample queries before saving
• Document the purpose of each segment in the description

Organization

• Create segments for your most common analyses
• Delete unused segments to keep your list clean
• Use consistent naming patterns across related segments
• Share segment definitions with your team for consistency

Performance

• Keep filter count reasonable (under 10 filters per segment)
• Use indexed fields when possible (country, device, browser)
• Avoid overly complex regex patterns in contains operators

Segment vs Filter

Filters are temporary conditions applied to a single view or report.Segments are saved, reusable filter combinations that can be applied across multiple dashboards, reports, and analyses.

Use segments when:

• You analyze the same user group regularly
• You need consistent definitions across your team
• You want to track trends for specific audiences over time

Use one-time filters when:

• You're exploring data and trying different combinations
• You need a quick, ad-hoc analysis
• The filter criteria won't be reused