Cohorts & Segmentation

Cohorts let you group subscribers into named segments for targeted notification delivery, performance tracking, and A/B comparisons. Create static cohorts with manually managed membership, or dynamic cohorts that automatically match subscribers based on rules.

Overview

Feature	Description
Static Cohorts	Manually add/remove members
Dynamic Cohorts	Auto-populate based on filter rules
Metrics	Track delivery, engagement, and conversion per cohort
Snapshots	Capture membership over time for trend analysis
Comparisons	A/B compare metrics between cohorts

Quick Start

Create a Cohort

curl -X POST https://api.zyphr.dev/v1/cohorts \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Power Users",
    "slug": "power-users",
    "type": "static",
    "description": "Users with 10+ logins in the last 30 days"
  }'

const cohort = await zyphr.cohorts.create({
  name: 'Power Users',
  slug: 'power-users',
  type: 'static',
  description: 'Users with 10+ logins in the last 30 days',
});

Add Members

curl -X POST https://api.zyphr.dev/v1/cohorts/power-users/members \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_ids": ["user_123", "user_456", "user_789"]
  }'

View Metrics

curl "https://api.zyphr.dev/v1/cohorts/power-users/metrics?start_date=2026-02-01&end_date=2026-02-28&channel=email" \
  -H "X-API-Key: zy_live_your_api_key"

Creating Cohorts

Static Cohorts

Membership is explicitly managed — you add and remove subscribers:

curl -X POST https://api.zyphr.dev/v1/cohorts \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beta Testers",
    "slug": "beta-testers",
    "type": "static"
  }'

Dynamic Cohorts

Membership is automatically determined by filter rules:

curl -X POST https://api.zyphr.dev/v1/cohorts \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Users",
    "slug": "enterprise-users",
    "type": "dynamic",
    "rules": {
      "operator": "and",
      "conditions": [
        { "field": "metadata.plan", "operator": "eq", "value": "enterprise" },
        { "field": "metadata.status", "operator": "eq", "value": "active" }
      ]
    }
  }'

Cohort Parameters

Parameter	Type	Required	Description
name	string	Yes	Human-readable name
slug	string	No	URL-safe identifier (auto-generated from name if omitted)
type	string	Yes	static or dynamic
description	string	No	Description of the cohort's purpose
rules	object	Dynamic only	Filter rules for automatic membership

List Cohorts

curl "https://api.zyphr.dev/v1/cohorts?status=active&page=1&per_page=25" \
  -H "X-API-Key: zy_live_your_api_key"

Update a Cohort

curl -X PATCH https://api.zyphr.dev/v1/cohorts/COHORT_ID \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "description": "Updated description"
  }'

Delete a Cohort

curl -X DELETE https://api.zyphr.dev/v1/cohorts/COHORT_ID \
  -H "X-API-Key: zy_live_your_api_key"

Managing Members

Add Members (Static Cohorts)

curl -X POST https://api.zyphr.dev/v1/cohorts/COHORT_ID/members \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_ids": ["user_123", "user_456"]
  }'

await zyphr.cohorts.addMembers(cohortId, {
  subscriberIds: ['user_123', 'user_456'],
});

Remove Members

curl -X DELETE https://api.zyphr.dev/v1/cohorts/COHORT_ID/members \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_ids": ["user_123"]
  }'

List Members

curl "https://api.zyphr.dev/v1/cohorts/COHORT_ID/members?page=1&per_page=25" \
  -H "X-API-Key: zy_live_your_api_key"

note

For dynamic cohorts, the members endpoint returns the current matching subscribers based on the cohort's rules. You cannot add/remove members manually from dynamic cohorts.

Metrics & Analytics

Get Cohort Metrics

Track notification delivery and engagement metrics for a cohort:

curl "https://api.zyphr.dev/v1/cohorts/COHORT_ID/metrics?start_date=2026-02-01&end_date=2026-02-28&period_type=daily&channel=email" \
  -H "X-API-Key: zy_live_your_api_key"

Query Parameters

Parameter	Type	Required	Description
start_date	string	Yes	Start date (YYYY-MM-DD)
end_date	string	Yes	End date (YYYY-MM-DD)
period_type	string	No	Aggregation period: daily, weekly, monthly
channel	string	No	Filter by channel: email, push, sms, in_app

Calculate Metrics

Trigger a metrics calculation over a date range:

curl -X POST https://api.zyphr.dev/v1/cohorts/COHORT_ID/metrics/calculate \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-02-01",
    "end_date": "2026-02-28",
    "period_type": "weekly"
  }'

Snapshots

Capture a point-in-time record of cohort membership for trend analysis:

Create a Snapshot

curl -X POST https://api.zyphr.dev/v1/cohorts/COHORT_ID/snapshots \
  -H "X-API-Key: zy_live_your_api_key"

View Snapshots Over Time

curl "https://api.zyphr.dev/v1/cohorts/COHORT_ID/snapshots?start_date=2026-01-01&end_date=2026-02-28" \
  -H "X-API-Key: zy_live_your_api_key"

Returns an array of snapshots showing member count and composition at each point in time.

A/B Comparisons

Compare metrics between two or more cohorts side by side:

Create a Comparison

curl -X POST https://api.zyphr.dev/v1/cohorts/comparisons \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Free vs Pro Users",
    "cohort_ids": ["cohort_free", "cohort_pro"]
  }'

const comparison = await zyphr.cohorts.createComparison({
  name: 'Free vs Pro Users',
  cohortIds: ['cohort_free', 'cohort_pro'],
});

View Comparison Results

curl "https://api.zyphr.dev/v1/cohorts/comparisons/COMPARISON_ID?start_date=2026-02-01&end_date=2026-02-28" \
  -H "X-API-Key: zy_live_your_api_key"

List Comparisons

curl "https://api.zyphr.dev/v1/cohorts/comparisons?page=1&per_page=10" \
  -H "X-API-Key: zy_live_your_api_key"

Pin/Unpin Comparisons

Pin frequently used comparisons for quick access:

curl -X POST https://api.zyphr.dev/v1/cohorts/comparisons/COMPARISON_ID/pin \
  -H "X-API-Key: zy_live_your_api_key"

Plan Limits

Plan	Max Cohorts	Comparisons
Free	3	1
Starter	10	5
Pro	50	25
Scale	Unlimited	Unlimited
Enterprise	Unlimited	Unlimited

API Reference

Method	Endpoint	Description
POST	/v1/cohorts	Create cohort
GET	/v1/cohorts	List cohorts
GET	/v1/cohorts/:id	Get cohort
PATCH	/v1/cohorts/:id	Update cohort
DELETE	/v1/cohorts/:id	Delete cohort
POST	/v1/cohorts/:id/members	Add members
DELETE	/v1/cohorts/:id/members	Remove members
GET	/v1/cohorts/:id/members	List members
GET	/v1/cohorts/:id/metrics	Get metrics
POST	/v1/cohorts/:id/metrics/calculate	Calculate metrics
POST	/v1/cohorts/:id/snapshots	Create snapshot
GET	/v1/cohorts/:id/snapshots	View snapshots
POST	/v1/cohorts/comparisons	Create comparison
GET	/v1/cohorts/comparisons	List comparisons
GET	/v1/cohorts/comparisons/:id	View comparison
DELETE	/v1/cohorts/comparisons/:id	Delete comparison
POST	/v1/cohorts/comparisons/:id/pin	Toggle pin

Next Steps

• Subscribers - Manage the subscribers that populate cohorts
• Topics - Group subscribers by interest for fan-out delivery
• Usage & Analytics - Track platform-wide usage metrics