Skip to main content

​
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

FieldTypeRequiredDescription
segmentIdsstring[]YesArray of 2-10 segment IDs to compare
sampleSizeintegerNoMax 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

FieldTypeDescription
segmentsarrayEach segment’s ID, name, and sampled size
overlapsarrayPairwise overlap results
overlaps[].segmentsstring[]Pair of segment IDs
overlaps[].countintegerNumber of shared customers
overlaps[].percentintegerOverlap as percentage of the smaller segment
totalUniqueCustomersintegerDistinct customers across all segments
overlapWarningsstring[]Warnings when overlap exceeds 30%

​
Error Codes

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

​
Roles

admin, editor, viewer See also: Segments