Skip to main content
The Custom Cohort Segmentation (CCS) API enables real-time user segmentation by processing events against your workspace’s cohort definitions. This API is designed for server-side integrations where you need to determine a user’s cohort membership in real-time.

​
Overview

The CCS API provides two main endpoints:

Segmentation

Segment a user based on events and persist state for future requests.

Stateless Segmentation

Segment a user without persisting state - ideal for testing and high-performance scenarios.

​
Use Cases

  • Server-side targeting: Determine user cohorts server-side before making ad requests
  • Real-time personalization: Segment users in real-time based on their actions
  • SDK-less integrations: Integrate with Permutive without using client-side SDKs
  • AMP pages: Segment users on AMP pages where JavaScript SDK cannot run

​
Authentication

All endpoints require API key authentication. You can provide your API key in one of two ways:
  • Query parameter: ?k=your-api-key
  • Header: X-Api-Key: your-api-key
You can find your API key in the Permutive Dashboard under Settings.

​
Base URL

All API requests should be made to: 
https://api.permutive.app

​
Rate Limits

The CCS API is designed for high-throughput scenarios. Contact your Permutive representative for specific rate limit information for your workspace.

​
Batch Size

Each request can include up to 10 events. For larger batches, split your events across multiple requests.