Segment Overlap

Analyze customer overlap between multiple segments to identify redundancy and optimize targeting.

POST /api/v1/segments/overlap

Computes pairwise overlap between 2-10 segments by querying their underlying PostgreSQL views. Returns overlap counts, percentages, and warnings for high-overlap pairs.

Request Body

Field	Type	Required	Description
segmentIds	string[]	Yes	Array of 2-10 segment IDs to compare
sampleSize	integer	No	Max customers per segment to sample (100-50000, default: 5000)

Example

curl -X POST https://playground.kaireonai.com/api/v1/segments/overlap \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "segmentIds": ["seg_001", "seg_002", "seg_003"],
    "sampleSize": 10000
  }'

Response

{
  "segments": [
    { "id": "seg_001", "name": "High Value", "size": 4200 },
    { "id": "seg_002", "name": "Active Traders", "size": 3100 },
    { "id": "seg_003", "name": "Premium Tier", "size": 1800 }
  ],
  "overlaps": [
    { "segments": ["seg_001", "seg_002"], "count": 1250, "percent": 40 },
    { "segments": ["seg_001", "seg_003"], "count": 1100, "percent": 61 },
    { "segments": ["seg_002", "seg_003"], "count": 680, "percent": 38 }
  ],
  "totalUniqueCustomers": 6170,
  "overlapWarnings": [
    "61% of Premium Tier customers are also in High Value — consider merging or adjusting targeting",
    "40% of Active Traders customers are also in High Value — consider merging or adjusting targeting",
    "38% of Premium Tier customers are also in Active Traders — consider merging or adjusting targeting"
  ]
}

Response Fields

Field	Type	Description
segments	array	Each segment’s ID, name, and sampled size
overlaps	array	Pairwise overlap results
overlaps[].segments	string[]	Pair of segment IDs
overlaps[].count	integer	Number of shared customers
overlaps[].percent	integer	Overlap as percentage of the smaller segment
totalUniqueCustomers	integer	Distinct customers across all segments
overlapWarnings	string[]	Warnings when overlap exceeds 30%

Error Codes

Code	Reason
400	Fewer than 2 or more than 10 segment IDs
400	Segment not found or segment has no materialized view

Roles

admin, editor, viewer

See also: Segments