Skip to main content
POST
/
ctx
/
v1
/
segment
Get Contextual Segments
curl --request POST \
  --url https://api.permutive.com/ctx/v1/segment \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "page_properties": {
    "page_properties.client": {
      "page_properties.client.url": "<string>",
      "page_properties.client.domain": "<string>",
      "page_properties.client.referrer": "<string>",
      "page_properties.client.type": "<string>",
      "page_properties.client.user_agent": "<string>",
      "page_properties.client.title": "<string>"
    }
  }
}
'
{
  "cohorts": {},
  "activations": {},
  "contextual_data": {}
}

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.

Retrieve contextual cohort codes for a given URL and page properties. Returns cohort codes formatted for Google Ad Manager.

​
Request

​
Query Parameters

​
k
string
required
Your Permutive API key. This is the same API key used for your main Permutive SDK deployment.

​
Body Parameters

​
url
string
required
The URL to retrieve contextual cohorts for. This is typically the current page URL.
​
page_properties
object
required
An object containing page properties used for contextual classification. This should match the structure of properties you track in Pageview events, but must exclude any user-related data.
Personal Data: The request must not contain any user-related data points. Omit any user-related properties that you might be recording as part of your Pageview events.

​
Response

​
cohorts
array of strings
All contextual cohort codes for the page. This is the complete list of cohorts that matched.
​
activations
object
An object mapping activation destination names to arrays of cohort code strings. Each key is an activation destination (e.g., target_dfp, appnexus_adserver) and the value is an array of cohort codes configured for that destination.
​
contextual_data
object
An object containing content classification data, returned when a classification provider is enabled in the account. Includes classifications such as categories, keywords, entities, sentiment, emotion, and concepts.

​
Example Request

curl -X POST "https://api.permutive.com/ctx/v1/segment?k=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article/sports-news",
    "page_properties": {
      "client": {
        "url": "https://example.com/article/sports-news",
        "domain": "example.com",
        "referrer": "https://example.com",
        "type": "web",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "title": "Latest Sports News"
      },
      "category": "sports",
      "tags": ["football", "premier-league"]
    }
  }'

​
Example Response

{
  "cohorts": ["abc", "def", "ghi"],
  "activations": {
    "target_dfp": ["abc", "def"],
    "appnexus_adserver": ["ghi"]
  },
  "contextual_data": {
    "classifications": {
      "categories": [
        {
          "value": "155",
          "confidence": 0.5,
          "taxonomy": "iab_3.0",
          "provider": "ibm_watson"
        }
      ],
      "keywords": [
        {
          "value": "museum",
          "confidence": 0.7,
          "provider": "ibm_watson"
        }
      ],
      "entities": [
        {
          "value": "British Museum",
          "confidence": 0.9,
          "provider": "ibm_watson"
        }
      ],
      "sentiment": [
        {
          "value": "positive",
          "confidence": 0.9,
          "provider": "ibm_watson"
        }
      ],
      "emotion": [
        {
          "value": "joy",
          "confidence": 0.4,
          "provider": "ibm_watson"
        }
      ],
      "concepts": [
        {
          "value": "Vincent van Gogh",
          "confidence": 0.6,
          "provider": "ibm_watson"
        }
      ]
    }
  }
}

​
Implementation Notes

When passing targeting values to your ad server, always append rts to the array of cohort codes. This is required for proper targeting:
const targetingValues = apiResponse.activations.target_dfp.concat('rts');
Make the API call as early as possible when the page loads to ensure targeting is attached to the first ad call. We recommend placing the API call in the <head> of your page.
Use the same API key that you use for your main Permutive SDK deployment. This ensures cohorts are correctly associated with your workspace.

Activating in Google Ad Manager

Full implementation guide with code samples for Google Ad Manager.

API Introduction

Overview of the Contextual API.