Segments reference

A segment is a saved rule set over session_facts, the one-row-per-session table. Every segment compiles to a single SQL statement, so "watched 50% of the VSL but did not opt in" is literally max_video_pct >= 50 AND is_lead = false. The dashboard builder, the REST API (POST /segments, POST /segments/preview) and the MCP tools (create_segment, preview_segment) all take the same JSON.

1. Rule JSON#

{
  "target": "visitor",
  "window_days": 30,
  "site_id": "optional-site-uuid",
  "funnel_id": "optional-funnel-uuid",
  "all": [
    { "field": "max_video_pct", "op": ">=", "value": 50 },
    { "field": "is_lead", "op": "=", "value": false },
    { "any": [
      { "field": "clicked", "op": "contains", "value": "cta_pricing" },
      { "field": "max_scroll_pct", "op": ">=", "value": 75 }
    ]}
  ]
}

type SegmentTarget = 'session' | 'visitor' | 'person'
type Op = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'exists' | 'not_exists' | 'starts_with'
type Condition = { field: string; op: Op; value?: unknown }
type Group = { all: Node[] } | { any: Node[] } | { not: Node }
type Node = Condition | Group
type SegmentRules = { target: SegmentTarget; window_days: number; site_id?: string; funnel_id?: string } & Group

• all = AND, any = OR, not = negation. Groups nest without limit. An empty all matches everything, an empty any matches nothing.
• window_days (1..3650) limits sessions to started_at >= now() - window.
• site_id restricts to one site; funnel_id to sessions that reached any step of that funnel.
• Test sessions (is_test = true) are always excluded; this is not configurable.

2. Targets and aggregation#

Aggregation per field type when target is visitor or person:

session_count is the number of sessions per visitor/person inside the window and is only valid for those targets.

3. Operators by type#

exists / not_exists take no value. Empty strings count as not set.

4. Fields#

Custom fields#

Anything sent with rf.set({ plan_interest: 'premium', score: 42, vip: true }) lands in session_facts.custom and is queryable as custom.<key> (keys: [a-z0-9_]{1,64}). The type is inferred from the value in the condition:

{ "field": "custom.plan_interest", "op": "=", "value": "premium" }
{ "field": "custom.score", "op": ">=", "value": 40 }
{ "field": "custom.vip", "op": "=", "value": true }
{ "field": "custom.plan_interest", "op": "exists" }

5. Built-in templates#

• vsl_25_no_lead — VSL 25% – no lead (visitor, 30 days; sync: meta): Visitors in the last 30 days where max video % ≥ 25 and is lead = false
• vsl_50_no_lead — VSL 50% – no lead (visitor, 30 days; sync: meta): Visitors in the last 30 days where max video % ≥ 50 and is lead = false
• vsl_75_no_lead — VSL 75% – no lead (visitor, 30 days; sync: meta): Visitors in the last 30 days where max video % ≥ 75 and is lead = false
• quiz_abandoners — Quiz abandoners (visitor, 30 days; sync: meta): Visitors in the last 30 days where quiz last step ≥ 1 and quiz completed = false and is lead = false
• high_intent_no_lead — High intent – no lead (visitor, 30 days; sync: meta): Visitors in the last 30 days where max scroll % ≥ 75 and clicked is one of ['cta_pricing', 'cta_hero', 'cta_offer', 'cta_checkout', 'cta_buy', 'cta_book', 'cta_apply'] and is lead = false
• leads_no_booking — Leads without booking (person, 30 days; sync: meta, google): People in the last 30 days where is lead = true and is booked = false and is customer = false
• bookers_no_purchase — Bookers without purchase (person, 60 days; sync: meta, google): People in the last 60 days where is booked = true and is customer = false
• returning_no_lead — Returning visitors – no lead (visitor, 30 days; sync: meta): Visitors in the last 30 days where session count ≥ 3 and is lead = false
• checkout_abandoners — Checkout abandoners (visitor, 14 days; sync: meta, google): Visitors in the last 14 days where (clicked is one of ['cta_checkout', 'cta_buy', 'cta_add_to_cart', 'cta_order'] or scroll by path contains '/checkout') and is customer = false
• webinar_registered_no_show — Webinar registered – no show (person, 30 days; sync: meta, google): People in the last 30 days where is lead = true and is customer = false and not ((scroll by path contains '/live' or custom.webinar_attended is set))

Create them for a funnel with the MCP tool create_default_segments or from the dashboard.

6. What the compiler produces#

compileSegment(rules) returns { sql, params } with $1..$n placeholders; inlineParams(sql, params) renders a self-contained statement for fs_refresh_segment. Example for the rules above:

SELECT sf.visitor_id
FROM session_facts sf
WHERE sf.is_test = false
  AND sf.started_at >= now() - make_interval(days => $1)
  AND sf.visitor_id IS NOT NULL
GROUP BY sf.visitor_id
HAVING (MAX(sf.max_video_pct) >= $2 AND BOOL_OR(COALESCE(sf.is_lead, false)) = $3
  AND (COALESCE(BOOL_OR($4 = ANY(sf.clicked)), false) OR MAX(sf.max_scroll_pct) >= $5))

Only fields in the whitelist (SEGMENT_FIELDS) and custom.<key> are accepted; unknown fields or operators throw before any SQL is built. Values are always parameters, never interpolated.

7. Tips#

• Build retargeting pools on visitor (works for anonymous traffic through Meta CAPI); build suppression and Customer Match lists on person.
• Combine behaviour with the absence of an outcome: is_lead = false, is_booked = false, is_customer = false.
• Use describeRules(rules) (or the dashboard preview) to read a rule set back in English before saving it.
• Preview counts with preview_segment / POST /segments/preview before enabling sync.