> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contextual Cohorts

> Target ads based on page content without processing user data

export const NoBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#F7D0E2',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      No
    </span>;
};

export const YesBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#C7E8F9',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      Yes
    </span>;
};

<CardGroup cols={3}>
  <Card title="Guides" href="#guides" icon="book-open" />

  <Card title="Issues" href="#troubleshooting" icon="triangle-exclamation" />

  <Card title="FAQ" href="#faq" icon="circle-question" />
</CardGroup>

## Overview

**Contextual Cohorts** enable publishers to target ads based on contextual data derived from page content without processing or storing any user data. Since no user consent is required, Contextual Cohorts allow publishers to reach users who have not given consent and cannot be targeted with behavioral data today.

Contextual Cohorts work by analyzing page-level signals such as automated content classifications, editorial metadata, and affinity scores from consented users. This enables publishers to create a differentiated contextual targeting offering that combines the precision of content understanding with the unique insights from their first-party data.

## Why Use Contextual Cohorts?

**Reach users without consent requirements** — Contextual Cohorts operate entirely on page-level data, requiring no user consent. This enables publishers to monetize inventory from users who haven't consented to data collection, expanding addressable inventory while maintaining privacy compliance.

**Leverage multiple contextual signals in one place** — Permutive's Contextual Cohorts bring together multiple data sources including NLP classifications from providers like IBM Watson, editorial tagging from your CMS, third-party classification services, and affinity insights from consented users—all in a single platform.

**Build a differentiated contextual offering** — By combining automated content classifications with affinity scores derived from your first-party data, you can create contextual targeting that reflects your unique audience understanding and differentiates your advertising offering from generic contextual solutions.

**Maintain unified targeting management** — Manage both user-based targeting (Custom Cohorts) and contextual targeting (Contextual Cohorts) within the same dashboard, simplifying campaign setup and enabling consistent targeting logic across consent and non-consent scenarios.

## Concepts

### Definitions

* **Contextual Cohorts**: Audience segments built on page-level attributes rather than user-level data. They target content that matches specific criteria such as categories, keywords, sentiment, or affinity to Custom Cohorts. Because they operate purely on content data, they don't require user consent and can be used across all inventory.

* **Content Classifications**: Automated categorizations of your web content generated by NLP (Natural Language Processing) providers. These classifications extract structured data such as categories, concepts, entities, keywords, sentiment, and emotion.

* **Page Properties**: Custom metadata you collect about your content, including editorial tags (e.g., section, author, topic), in-house classifications, third-party classification data, and content metadata (e.g., word count, publish date). The available Page Properties mirror the custom properties from your Pageview event schema.

* **Affinity Cohorts**: Allow you to leverage insights from consented users to make contextual targeting decisions. Permutive calculates an affinity score for each URL based on how likely users in a specific Custom Cohort are to engage with that content compared to the site average. An affinity score of 100 indicates site average engagement, scores above 100 indicate higher engagement (e.g., 200 = 2x more likely), and scores below 100 indicate lower engagement.

* **Keyword Explorer**: An AI-powered feature that uses machine learning to offer keyword recommendations for building interest-based cohorts. By analyzing the similarities and connections between keywords, it suggests relevant terms that maximize both reach and relevance.

## Workflows

### Creating a Contextual Cohort

Publishers use the Contextual Cohort builder to define targeting rules using Content Classifications, Page Properties, or Affinity Cohorts. They select providers, configure dimensions, and combine multiple conditions using AND/OR logic to create precise contextual targeting criteria.

### Deploying and Managing Contextual Cohorts

All Contextual Cohorts are displayed in the Contextual section of the Permutive Dashboard. The cohort list provides an overview including cohort name, description, targeting logic, creation date, status (Enabled/Disabled), and pageview reach forecast (where available).

### Activating Contextual Cohorts

Contextual Cohorts can be activated to advertising platforms such as Google Ad Manager, Xandr, and other destinations. The Contextual API passes cohort memberships to these platforms in real-time for ad targeting based on the content users are currently viewing.

## Guides

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

<CardGroup cols={2}>
  <Card title="Creating Contextual Cohorts" icon="plus" href="/guides/signals/cohorts/contextual/creating-contextual-cohorts">
    Build audience segments based on page content
  </Card>

  <Card title="Enabling Classification Providers" icon="toggle-on" href="/guides/signals/cohorts/contextual/enabling-classification-providers">
    Enable and configure NLP classification providers
  </Card>

  <Card title="Previewing Classifications" icon="eye" href="/guides/signals/cohorts/contextual/previewing-classifications">
    Test how providers classify your content
  </Card>

  <Card title="Activating in Google Ad Manager" icon="bullseye" href="/guides/signals/cohorts/contextual/deploying-to-google-ad-manager">
    Activate contextual cohorts in GAM for ad targeting
  </Card>
</CardGroup>

Advanced use cases for Contextual Cohorts:

<CardGroup cols={2}>
  <Card title="Using Keyword Explorer" icon="wand-magic-sparkles" href="/guides/signals/cohorts/contextual/using-keyword-explorer">
    Get AI-powered keyword recommendations
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No classification provider enabled">
    **Cause**: You're trying to use Content Classifications but no classification provider is enabled for your workspace.

    **Solution**:

    * Navigate to *Contextual > Catalog*
    * Enable at least one provider by contacting your Customer Success Manager or entering your own API key
  </Accordion>

  <Accordion title="Property not available in Contextual API">
    **Cause**: You've selected a Page Property that isn't being passed to the Contextual API.

    **Solution**:

    * Review your Contextual API implementation
    * Ensure the property is included in the API call
    * Refer to the [Contextual API documentation](/api/contextual/introduction)
  </Accordion>

  <Accordion title="Custom Cohort not eligible for Affinity">
    **Cause**: You've selected a Custom Cohort that cannot be used for Affinity Cohorts (e.g., modeled cohort, standard cohort, or cohort using third-party data).

    **Solution**:

    * Select a different Custom Cohort built from first-party behavioral data
    * Ensure the cohort has sufficient engagement data for affinity score calculation
  </Accordion>

  <Accordion title="Classification quota exceeded">
    **Cause**: Your classification provider has reached its usage quota for the current time period.

    **Solution**:

    * Wait for the quota to reset (timeframe depends on provider settings)
    * Contact your Customer Success Manager to increase your quota
    * Optimize quota usage by restricting classifications to specific domains or using selective classification thresholds
  </Accordion>

  <Accordion title="Insufficient data for affinity calculation">
    **Cause**: The selected Custom Cohort doesn't have enough engagement data to calculate reliable affinity scores.

    **Solution**:

    * Allow more time for engagement data to accumulate
    * Use cohorts with higher traffic or engagement levels
    * Consider alternative targeting methods (Content Classifications or Page Properties)
  </Accordion>

  <Accordion title="Contextual API not implemented">
    **Cause**: The Contextual API hasn't been integrated on your website, so contextual cohorts cannot be deployed.

    **Solution**:

    * Follow the [Contextual API implementation guide](/api/contextual/introduction)
    * Contact [Technical Services](mailto:technical-services@permutive.com) for implementation support
    * Verify implementation using browser developer tools (look for `segment?k=*API_KEY*` requests)
  </Accordion>
</AccordionGroup>

## Environment Compatibility

#### Core Product

Contextual Cohorts functionality is supported on the following platforms:

| Functionality                | Web          | iOS          | Android      | CTV                   | API Direct   |
| :--------------------------- | :----------- | :----------- | :----------- | :-------------------- | :----------- |
| Cohort creation & management | <YesBadge /> | <YesBadge /> | <YesBadge /> | <YesBadge />          | <YesBadge /> |
| Content classification       | <YesBadge /> | <YesBadge /> | <YesBadge /> | Varies by environment | <NoBadge />  |
| Contextual API               | <YesBadge /> | <YesBadge /> | <YesBadge /> | Varies by environment | <NoBadge />  |
| Cohort activation            | <YesBadge /> | <YesBadge /> | <YesBadge /> | Varies by environment | <NoBadge />  |

#### Platform-Specific Notes

| Platform | Support | Notes                                                      |
| :------- | :-----: | :--------------------------------------------------------- |
| Web      |    ✓    | Full support for all features                              |
| iOS      |    ✓    | Full support for all features                              |
| Android  |    ✓    | Full support for all features                              |
| CTV      |    \~   | Support depends on specific environment and implementation |

#### Activation

Contextual Cohorts can currently be activated to the following destinations:

* Google Ad Manager
* Xandr

## Dependencies

Contextual Cohorts rely on the following products and features being configured for your organization:

| Dependency             | Required | Description                                                                                                                                      |
| :--------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| Contextual API         | ✓        | The Contextual API must be implemented on your website to enable real-time cohort deployment and activation.                                     |
| Content Classification | \~       | Required if building cohorts based on NLP classifications (IBM Watson, TextRazor, etc.). Not required if using only Page Properties or Affinity. |
| Custom Cohorts         | \~       | Required only for Affinity Cohorts. You must have Custom Cohorts created with sufficient consented user engagement data.                         |
| Permutive SDK          | \~       | Required for collecting user engagement data that powers Affinity Cohort calculations. Not required for basic Content Classification cohorts.    |

## Limits

Contextual Cohorts adhere to the following product specifications and limits.

#### Feature Limits

| Feature                           | Description                                                               | Limit              |
| :-------------------------------- | :------------------------------------------------------------------------ | :----------------- |
| Content classification providers  | The number of classification providers that can be enabled simultaneously | Multiple supported |
| Contextual cohort rule complexity | The maximum number of conditions and AND/OR statements in a single cohort | No hard limit      |
| Taxonomies per provider           | The number of taxonomies supported by a classification provider           | Varies by provider |

#### Performance Limits

| Metric                       | Description                                                            | Limit                                      |
| :--------------------------- | :--------------------------------------------------------------------- | :----------------------------------------- |
| Classification time          | The time it takes to classify a new URL                                | Varies by provider (typically 2-5 seconds) |
| Contextual API response time | The time for the Contextual API to return cohort memberships for a URL | \< 100ms                                   |

#### Usage Limits

| SKU                     | Description                              | Limit                           |
| :---------------------- | :--------------------------------------- | :------------------------------ |
| Contextual Cohorts      | Maximum contextual cohorts per workspace | \[Contact support]              |
| Content Classifications | Classification quota per provider        | Varies by provider and contract |

#### Data Retention

Content classifications are cached and retained to optimize performance and quota usage. Classification data may be refreshed based on content update frequency and provider settings.

## Content Classification Providers

Permutive supports multiple content classification providers, allowing you to choose the best solution for your content and requirements.

### Available Providers

| Provider               | Status      | Categories | Keywords | Entities | Concepts | Sentiment | Emotion |
| :--------------------- | :---------- | :--------: | :------: | :------: | :------: | :-------: | :-----: |
| IBM Watson             | ✓ Available |      ✓     |     ✓    |     ✓    |     ✓    |     ✓     |    ✓    |
| TextRazor              | ✓ Available |      ✓     |          |     ✓    |     ✓    |           |         |
| OS Data Solutions      | ✓ Available |      ✓     |     ✓    |     ✓    |     ✓    |     ✓     |    ✓    |
| Silverbullet 4D        | ✓ Available |      ✓     |          |          |          |           |         |
| Permutive Brand Safety | ✓ Beta      |      ✓     |          |          |          |           |         |
| Webhook (Custom)       | ✓ Available |      ✓     |     ✓    |     ✓    |     ✓    |     ✓     |    ✓    |

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between Contextual Cohorts and Custom Cohorts?">
    **Custom Cohorts** target users based on their behavior and data, requiring user consent. **Contextual Cohorts** target page content without processing user data, requiring no consent. Contextual Cohorts allow you to reach non-consented users by targeting the content they're viewing rather than their behavioral profile.
  </Accordion>

  <Accordion title="Can I use Contextual Cohorts and Custom Cohorts together?">
    Yes! You can use both targeting approaches in parallel or combine them strategically. For example, use Custom Cohorts for consented users and fall back to Contextual Cohorts for non-consented users. Additionally, you can use Affinity Cohorts to apply insights from Custom Cohorts to contextual targeting.
  </Accordion>

  <Accordion title="How do affinity scores work for large cohorts?">
    Affinity scores are normalized against cohort size to prevent large cohorts from dominating scores. However, for very large cohorts, affinity scores will gravitate toward 100. An extreme example: an "everyone" cohort will have an affinity score of 100 for any URL since it represents the site average.
  </Accordion>

  <Accordion title="What affinity score threshold should I use?">
    We generally recommend starting with a threshold greater than 200 (2x or 100% more likely to engage). Higher thresholds provide more relevance but less scale. You can test different thresholds based on your campaign needs and audience characteristics.
  </Accordion>

  <Accordion title="Which classification provider should I choose?">
    The best provider depends on your content type, language, and specific requirements:

    * **IBM Watson**: Comprehensive dimensions including sentiment and emotion, strong multi-language support
    * **TextRazor**: Excellent for entity extraction and conceptual analysis
    * **OS Data Solutions**: Optimized for German publishers, includes BVDW taxonomy
    * **Permutive Brand Safety**: Focused on brand safety and suitability classifications

    Use the Preview feature to test different providers against your content.
  </Accordion>

  <Accordion title="How often is content classified?">
    Content is typically classified when first discovered or when Pageview traffic exceeds your selective classification threshold. Classifications are cached to optimize quota usage. The refresh frequency depends on your provider settings and content update patterns.
  </Accordion>

  <Accordion title="Can I edit a Contextual Cohort after creation?">
    Editing capabilities vary based on your configuration and provider. Some cohorts can be edited directly in the dashboard, while others may require creating a new cohort. Check the individual cohort settings to see if editing is available.
  </Accordion>

  <Accordion title="Why don't I see pageview reach forecasts?">
    Pageview reach forecasts may not be available for all cohorts depending on:

    * Data availability for the specified conditions
    * Cohort complexity
    * Provider limitations

    Reach forecasts are being progressively rolled out across all contextual cohort types.
  </Accordion>

  <Accordion title="Can I export my Contextual Cohorts?">
    Export functionality for Contextual Cohorts is currently in development. Contact your Customer Success Manager for updates on availability.
  </Accordion>

  <Accordion title="Do Contextual Cohorts work with Google Publisher Provided Signals (PPS)?">
    Yes! Permutive's Contextual Cohorts (when configured as Standard Contextual Cohorts) can be exposed to demand platforms via Google AdX through Publisher Provided Signals, enabling buyers to bid more intelligently based on your first-party contextual signals.
  </Accordion>
</AccordionGroup>

## Changelog

### 2024

**November 2024**

* Added provider preview functionality to the Catalog
* Improved quota management and selective classification thresholds
* Enhanced Affinity Cohort visualization in the dashboard

**June 2024**

* Expanded support for multiple classification providers
* Added custom taxonomy support via Webhook integration
* Introduced unified Content Classifications architecture

**March 2024**

* Released Permutive Brand Safety provider (beta)
* Added support for confidence thresholds in cohort targeting

### 2023

**October 2023**

* Introduced pageview reach forecasts for select cohort types
* Enhanced Affinity Cohort methodology with normalized scoring

**July 2023**

* Added OS Data Solutions provider with BVDW taxonomy support
* Expanded editing capabilities for existing contextual cohorts

**April 2023**

* Introduced TextRazor provider integration
* Added support for IAB 3.0 taxonomy

### 2022

**December 2022**

* Launched Affinity Cohorts for contextual targeting
* Added Page Properties support for editorial metadata

**September 2022**

* Released Contextual Cohorts with IBM Watson integration
* Introduced Contextual API for real-time targeting

<Info>
  For detailed changelog information, visit our
  [Changelog](https://changelog.permutive.com/).
</Info>