User segments

Define cohorts of users (e.g. 'high-LTV', 'cart-abandoners', 'new-this-week') and target recommendations to them.

User segments are named filters over your analytics event stream. Once defined, you can pass segment=<id> to any recommendation endpoint and the engine will score only against that cohort's history.

Segments live in SearchUsageEvent / analytics — there is no separate user-profile store. AACsearch is event-sourced.

CRUD endpoints

Method	Path	Action
`GET`	`/recommendations/user-segments`	List segments for the org.
`POST`	`/recommendations/user-segments`	Create.
`PATCH`	`/recommendations/user-segments/{id}`	Update rules.
`DELETE`	`/recommendations/user-segments/{id}`	Delete.
`GET`	`/recommendations/user-segments/{id}/stats`	Member count + activity rollup.

Segment definition

A segment is a JSON rule expression:

{
  "name": "high-LTV",
  "rules": {
    "op": "AND",
    "conditions": [
      { "field": "order_total", "agg": "sum", "window": "90d", "op": ">=", "value": 500 },
      { "field": "order_count", "agg": "count", "window": "90d", "op": ">=", "value": 3 }
    ]
  }
}

Supported agg: sum, count, avg, min, max, last. Supported op: >=, <=, =, !=, in, not_in.

Targeting a segment

Pass the segment id to any recommendation endpoint:

GET /recommendations/personalized?indexId=<id>&userId=<id>&segment=seg_abc&limit=10

The engine restricts the history walked / co-occurrences computed to users in that segment. Results stay scoped to the seed user, but the signal comes from segment-mates.

Useful patterns:

segment=high-LTV on a homepage rail to surface what high-value users buy.
segment=cart-abandoners in an email to surface what recoverers eventually purchase.
segment=new-this-week on onboarding to anchor first-session users to popular-among-new-users.

Stats endpoint

GET /recommendations/user-segments/seg_abc/stats

Returns:

{
  "id": "seg_abc",
  "memberCount": 1247,
  "trailingActivity": { "events_7d": 8419, "events_30d": 31_002 },
  "lastComputedAt": "2026-05-11T22:00:00Z"
}

Member count is recomputed nightly. For instant recompute, call POST /recommendations/user-segments/{id}/refresh (not yet documented, hits the same code path as the nightly job).

Quota cost

Segment CRUD is free — no Search Unit cost. Segment-targeted recommendation calls cost the same as any other recommendation call (1 SU each).

Code path

packages/api/modules/recommendations/procedures/user-segments.ts. Segments are stored as JSON rule trees alongside the analytics event corpus, evaluated lazily at recommendation time (no materialized membership table — that simplifies inserts at the cost of stats freshness).