Skip to main content

Guides

Issues

FAQ

​
Overview

Custom Cohorts enable publishers to build flexible, granular audience segments based on any combination of user behaviors, properties, and data sources. These cohorts are computed on device for real-time targeting and activation. Publishers can create cohorts using first-party data (behaviors on their properties), second-party data (partner data), and third-party data, allowing for highly customized audience targeting that meets specific campaign needs and advertiser requirements.

​
Why Use Custom Cohorts?

Build audiences for any campaign need — Custom Cohorts provide publishers with complete flexibility to create audience segments tailored to specific campaigns and advertiser briefs. Whether targeting users based on content engagement, recency, frequency, or custom event properties, Custom Cohorts enable publishers to meet diverse targeting requirements. Leverage multiple data sources — Build cohorts not just from your own first-party behavioral data, but also incorporate second-party data from partners and third-party data providers. This allows publishers to enrich their audience understanding and create more valuable, targetable segments for advertisers. Real-time Edge Computation — Custom Cohorts are computed on the Edge, enabling real-time user segmentation and activation on device. This ensures that your audience targeting is always current and responsive to user behavior as it happens.

​
Concepts

​
Definitions

  • Custom Cohort: A publisher-defined audience segment that groups users based on specific rules and conditions. Users are added to or removed from cohorts in real-time as they meet or no longer meet the cohort criteria.
  • Cohort Builder: The UI tool within the Permutive Dashboard that allows publishers to create and manage Custom Cohorts using a visual, no-code interface.
  • Event: An action or occurrence that is tracked by the Permutive SDK, such as a Pageview, VideoView, or custom event. Events form the foundation of cohort definitions.
  • Properties: Attributes associated with events that provide additional context, such as client.url, client.title, or custom properties. Properties enable fine-grained filtering when building cohorts.
  • Recency: The time window in which a user must have performed an action to qualify for a cohort (e.g., “in the past 30 days”).
  • Frequency: The number of times a user must have performed an action to qualify for a cohort (e.g., “at least 3 times”).
  • User Group Cohort: A special type of Custom Cohort that targets groups of users (such as households) rather than individual users. Behavior is aggregated across the entire group.

​
Workflows

​
Creating a Custom Cohort

Publishers use the Cohort Builder to define rules for their audience segments. They select events, specify properties, set recency and frequency requirements, and combine multiple conditions using AND/OR logic to create precise targeting criteria. Creating a custom cohort

​
Deploying a Custom Cohort

Once a Custom Cohort is created and validated with an audience size calculation, you can control whether it is deployed to the Permutive SDK via the cohort’s status toggle (on/off) on the cohort list page. The status toggle determines whether the cohort gets included for evaluation in the SDK:
  • On (enabled): The cohort is included in the SDK and users will be evaluated against it in real-time
  • Off (disabled): The cohort is not included in the SDK and users will not be evaluated against it
Enabling or disabling a cohort triggers an automatic rebuild of your SDK. The cohort change should be available shortly thereafter (typically within 2-5 minutes). Once deployed and enabled, the SDK evaluates users in real-time against the cohort criteria as they interact with your properties. Deploying a custom cohort All Custom Cohorts are displayed in the Custom Cohorts section of the Permutive Dashboard. The Cohort List provides an overview including cohort name, cohort code, tags, audience size, precision type (User or User Group), date created (UTC), status (Enabled/Disabled), and cohort logic. You can filter and sort cohorts by various attributes to find specific cohorts or analyze your cohort inventory.

​
Activating a Custom Cohort

Custom Cohorts can be activated to advertising platforms such as Google Ad Manager, Xandr, or other destinations. Activations can be configured during cohort creation or added later from the cohort management interface. The Permutive SDK manages passing cohort memberships to these platforms in real-time for ad targeting. Activating a custom cohort

​
Guides

Step-by-step instructions for working with Custom Cohorts.

Creating Custom Cohorts

Build a new audience segment using the Cohort Builder

Editing Custom Cohorts

Modify existing cohort rules and settings

Deleting Custom Cohorts

Remove cohorts from your project

Exporting Custom Cohorts

Export a report of all cohorts
Advanced use cases for Custom Cohorts:

Targeting Users by ISP

Create cohorts based on Internet Service Provider

Using Audience Imports

Build cohorts from external data sources

Creating User Group Cohorts

Target households instead of individuals

​
Troubleshooting

The following errors may occur when working with Custom Cohorts:
If your cohort fails to calculate an audience size, this may be due to:
  • Complex cohort rules that time out during calculation
  • Using unsupported event types or properties
  • Data processing delays
Solution: Try simplifying your cohort rules, verify that the events and properties exist in your data, and wait a few minutes before trying again. If the issue persists, contact Support.
If your cohort shows zero or very few users, check:
  • The recency window may be too short
  • The frequency threshold may be too high
  • Event properties may have typos or incorrect values
  • Events may not be firing as expected on your properties
Solution: Broaden your criteria, verify event tracking is working correctly, and check property values in the Event Inspector.
Cohort save errors typically occur due to:
  • Missing required fields (name, tags)
  • Invalid cohort logic or syntax
  • Permissions issues
Solution: Ensure all required fields are filled out, review your cohort logic for any issues, and verify you have permission to create cohorts in your workspace.
If a cohort is not showing up in your activation platform:
  • The activation may not be properly configured
  • There may be a delay in cohort deployment (typically a few minutes)
  • The cohort may have no users qualifying for it
  • API keys or integrations may not be properly set up
Solution: Verify activation configuration, wait a few minutes for deployment, check cohort audience size, and ensure integration credentials are correct.

​
Environment Compatibility

​
Core Product

Custom Cohorts functionality is supported on the following platforms:
FunctionalityWebiOSAndroidCTVAPI Direct
Cohort creation & managementYesYesYesYesYes
Event collectionYesYesYesYesYes
Real-time segmentationYesYesYesYesYes
Cohort activationYesYesYesYesYes *
* For API Direct, activation information is returned in the response from the Permutive API, but the client is typically responsible for integrating with the activation destination.

​
Activation

Custom Cohorts can be activated to all standard Permutive activation destinations, including:
  • Google Ad Manager
  • Xandr
  • Amazon Publisher Services
  • Prebid-supported SSPs (Magnite, Rubicon, etc.)
  • And many more via our activation integrations
For a complete list of supported activation destinations, please see our Integrations documentation.

​
User Group Cohorts

User Group Cohorts have limited platform support:
FunctionalityWebiOSAndroidCTVAPI Direct
Event collectionYesYesYesYesYes
ActivationYesNoNoNoYes *
* Activation information is returned in the response from the Permutive API, but the client is responsible for integrating with the activation destination. User Group cohorts are activated against User IDs, not Group IDs.

​
Dependencies

Custom Cohorts rely on the following products and features being configured for your organization:
DependencyRequiredDescription
Permutive SDK✓The Permutive SDK (Web, iOS, Android, or CTV) must be deployed to track events and enable real-time cohort evaluation and activation.
Event Tracking✓Events must be properly tracked and transmitted to Permutive for cohorts to function. At minimum, Pageview events are required.
Identity Graph~When using second-party data or User Group Cohorts, appropriate identifiers must be configured in Identity Graph and shared between you and the data partner.
Connectivity~Required for importing user group membership data when using User Group Cohorts, or for certain advanced cohort use cases.
Audience Imports~Required only if building cohorts based on external user lists or segments (second-party or third-party data).

​
Limits

Custom Cohorts adhere to the following product specifications and limits.

​
Feature Limits

FeatureDescriptionLimit
Cohort rule complexityThe maximum number of conditions, AND/OR statements, and nested logic in a single cohort.No hard limit
User Group identifier typesThe number of user group identifier types supported per organization.Multiple supported
Custom event typesThe number of custom event types that can be used in cohort definitions.No limit

​
Performance Limits

MetricDescriptionLimit
Audience size calculation timeThe time it takes to calculate historical audience size for a cohort.~30 seconds to 2 minutes
Cohort deployment timeThe time it takes for a newly created cohort to be available in the SDK for evaluation.2-5 minutes
Activation deployment timeThe time it takes for a newly created or updated cohort to be available in activation platforms.2-5 minutes

​
Usage Limits

SKUDescriptionLimit
Custom CohortsMaximum number of active Custom Cohorts per workspace.[Contact support]

​
FAQ

Custom Cohorts are publisher-defined segments built flexibly based on any combination of your first-party, second-party, and third-party data. Standard Cohorts are pre-defined, common audience segments based on NLP content classification that provide a standardized taxonomy across publishers for advertiser targeting.
Yes, Custom Cohorts support VideoView and VideoEngagement events, allowing you to target users based on video viewing behavior. Note that VideoEngagement events may not be supported in all query contexts.
For new users, cohort evaluation happens in near real-time (typically under 1 second) as they interact with your properties. The historical audience size calculation shows users from the past 30 days who would have qualified.
Yes, you can export your Custom Cohorts list from the Cohort List view in the Permutive Dashboard. See our Exporting Custom Cohorts guide for step-by-step instructions.
When you delete a Custom Cohort, it is immediately removed from all activations. Users in that cohort will no longer be targeted based on that cohort criteria. This action cannot be undone.
User Group Cohorts (also called Household Cohorts) aggregate behavior across a small group of users (such as a household) rather than individual users. This allows for household-level targeting. See our Creating User Group Cohorts guide for details.
Yes, Custom Cohorts are supported by our CCS API. The API enables you to pass event data directly to Permutive’s API and receive cohort IDs for a given device/user in the response. This is useful for environments where SDK deployment is not feasible.
There is no hard limit on cohort complexity, but very complex cohorts with many nested conditions may take longer to calculate audience size and could impact performance. We recommend keeping cohorts as simple as possible while meeting your targeting needs.
Yes, you can duplicate a cohort directly from the Custom Cohorts list. Click the menu icon (⋮) next to the cohort and select Duplicate. The duplicated cohort will be created with the same rules and a “(Copy)” suffix in the name.For bulk cohort duplication across workspaces, contact Support for assistance.

​
Changelog

No changes listed yet. For detailed changelog information, visit our Changelog.