Segments Quickstart

A segment is a group of users picked out by a rule tree. Amba re-evaluates every segment every 15 minutes; segment_memberships holds the current snapshot.

1. Create a segment

Via MCP

amba_create_segment({
  project_id: "proj_xxx",
  name: "Power Users",
  description: "Active in the last 7 days with 5+ day streak",
  rules: {
    operator: "AND",
    conditions: [
      { field: "last_seen_at", op: "within", value: "7d" },
      { field: "properties.streak_count", op: "gte", value: 5 }
    ]
  }
})

Via the Admin API

POST /admin/segments
 
{
  "name": "Power Users",
  "description": "Active in the last 7 days with 5+ day streak",
  "rules": {
    "operator": "AND",
    "conditions": [
      { "field": "last_seen_at", "op": "within", "value": "7d" },
      { "field": "properties.streak_count", "op": "gte", "value": 5 }
    ]
  }
}

Response 201 contains the new segment id — capture it for the next step.

2. Trigger an immediate evaluation

The background workflow evaluates every 15 minutes. To evaluate a single segment right now:

POST /admin/segments/:id/evaluate

Response echoes the updated user_count and timestamps.

3. Verify membership

GET /admin/segments/:id

The user_count field reflects the most recent evaluation. To inspect individual members, query your project's database:

SELECT app_user_id, entered_at
FROM segment_memberships
WHERE segment_id = $1;

4. Target a push campaign

amba_create_push_campaign({
  project_id: "proj_xxx",
  title: "Nice streak!",
  body: "You're on a roll — keep going.",
  segment_id: "<segment_id>"
})

Push delivery resolves segment membership at send time, not create time — if a user dropped out of the segment between the create and the send, they will not be notified.

Built-in segments

Every project ships with system segments (not editable, not deletable):

• All Users — every app_users row.
• Active (7d) — last_seen_at within "7d".
• Active (30d) — last_seen_at within "30d".
• New Users — created_at within "7d".

Use them as-is, or reference them in other features (remote config overrides, content schedules, etc.).

How rules compose

Conditions are ANDed or ORed under a top-level operator. Each condition is { field, op, value }. No nesting today — complex logic goes through multiple segments.

{
  "operator": "OR",
  "conditions": [
    { "field": "properties.plan", "op": "eq", "value": "premium" },
    { "field": "entitlements.is_active", "op": "eq", "value": true }
  ]
}

See Operators for the 12 supported comparators.

Performance

Rule evaluation runs as a single SQL query against app_users. Property paths are bound as text[] and fed to #>>, interval amounts are bound parameters, and both entitlement columns and app-user columns are whitelisted — admin-authored rules cannot inject SQL.

Segments with millions of users still evaluate in seconds. For very hot segments, the 15-minute cadence is intentional — push targeting rarely needs sub-minute freshness.

Next

• Operators — every comparator with examples.
• Push campaigns — fire pushes at a segment.
• Remote config — override config values per segment.