Cohorts

Cohorts are reusable audience segments that you can reference in flag targeting rules. Instead of repeating the same conditions across multiple flags, define a cohort once and target it everywhere with in_cohort / not_in_cohort.

Cohort Types

Flaggr supports three cohort types, each suited to a different workflow:

Creating a Cohort

Static Cohort

curl -X POST /api/cohorts \
  -H "Content-Type: application/json" \
  -d '{
    "id": "cohort-beta-testers",
    "projectId": "proj-123",
    "name": "Beta Testers",
    "type": "static",
    "members": ["user-42", "user-108", "user-291"]
  }'

Static cohorts maintain an explicit list of targetingKey values. You can add or remove members at any time via the API.

Rule-Based Cohort

curl -X POST /api/cohorts \
  -H "Content-Type: application/json" \
  -d '{
    "id": "cohort-enterprise-us",
    "projectId": "proj-123",
    "name": "US Enterprise Users",
    "type": "rule-based",
    "rules": {
      "conditions": [
        { "property": "plan", "operator": "equals", "value": "enterprise" },
        { "property": "country", "operator": "in", "value": ["US", "CA"] }
      ],
      "conditionOperator": "and"
    }
  }'

Rule-based cohorts evaluate their conditions dynamically at flag evaluation time. No member list is maintained — every evaluation checks the context against the cohort's rules.

Computed Cohort

curl -X POST /api/cohorts \
  -H "Content-Type: application/json" \
  -d '{
    "id": "cohort-high-value",
    "projectId": "proj-123",
    "name": "High-Value Customers",
    "type": "computed",
    "source": {
      "type": "csv",
      "config": { "url": "https://data.example.com/high-value-users.csv" },
      "syncInterval": 3600
    }
  }'

Computed cohorts hold a member list that is periodically refreshed from an external source. The syncInterval is in seconds. Sync the members via the API:

curl -X PATCH /api/cohorts/cohort-high-value \
  -H "Content-Type: application/json" \
  -d '{ "members": ["user-1", "user-2", "user-3"] }'

Using Cohorts in Targeting Rules

Reference a cohort in any targeting rule with the in_cohort or not_in_cohort operator:

{
  "targeting": [
    {
      "id": "beta-only",
      "conditions": [
        {
          "property": "targetingKey",
          "operator": "in_cohort",
          "value": true,
          "cohortId": "cohort-beta-testers"
        }
      ],
      "value": true
    }
  ]
}

You can combine cohort conditions with other conditions:

{
  "targeting": [
    {
      "id": "enterprise-beta",
      "conditions": [
        {
          "property": "targetingKey",
          "operator": "in_cohort",
          "value": true,
          "cohortId": "cohort-beta-testers"
        },
        {
          "property": "plan",
          "operator": "equals",
          "value": "enterprise"
        }
      ],
      "conditionOperator": "and",
      "value": true
    }
  ]
}

This rule matches users who are in the beta testers cohort AND on the enterprise plan.

Excluding Cohorts

Use not_in_cohort to exclude users:

{
  "conditions": [
    {
      "property": "targetingKey",
      "operator": "not_in_cohort",
      "value": true,
      "cohortId": "cohort-internal-team"
    }
  ]
}

Sync vs Async Evaluation

Cohort conditions require async evaluation because the cohort definition must be resolved at evaluation time. Flaggr provides two evaluation paths:

For server-side API evaluation, cohorts are resolved automatically. Client SDKs receive pre-evaluated results and don't need to resolve cohorts locally.

Managing Members

Add Members to a Static Cohort

curl -X PATCH /api/cohorts/cohort-beta-testers \
  -H "Content-Type: application/json" \
  -d '{ "members": ["user-42", "user-108", "user-500"] }'

Duplicate members are automatically deduplicated. Static cohorts support up to 100,000 members.

Remove Members

Update the cohort with a filtered member list, or use the member management operations in the cohort store API.

API Reference

Limits

Best Practices

• Prefer rule-based cohorts for segments that can be expressed as conditions — they stay current automatically
• Use static cohorts for curated lists that require manual control (beta testers, internal team)
• Keep computed cohorts small — large member lists increase memory usage
• Combine cohorts with other conditions — use in_cohort alongside plan/country/date checks
• Name cohorts descriptively — they appear in targeting rule UIs across all flags

Related

• Targeting Rules — Conditions, operators, and evaluation order
• Progressive Rollouts — Staged flag deployment with safety checks
• Overrides & Prerequisites — Identity overrides and flag dependencies