Segments Quickstart

A segment is a group of users picked out by a rule tree. Amba re-evaluates segments within 15 minutes of a change to your users' data (see Evaluation cadence); segment_memberships holds the current snapshot.

1. Create a segment

Via MCP

amba_segments_create({
  project_id: "proj_xxx",
  name: "Active Subscribers",
  description: "Active in the last 7 days with an active entitlement",
  rules: {
    operator: "AND",
    conditions: [
      { field: "last_seen_at", op: "within", value: "7d" },
      { field: "entitlements.is_active", op: "eq", value: true }
    ]
  }
})

Via the Admin API

POST /v1/admin/projects/:projectId/segments
 
{
  "name": "Active Subscribers",
  "description": "Active in the last 7 days with an active entitlement",
  "rules": {
    "operator": "AND",
    "conditions": [
      { "field": "last_seen_at", "op": "within", "value": "7d" },
      { "field": "entitlements.is_active", "op": "eq", "value": true }
    ]
  }
}

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

2. Trigger an immediate evaluation

The background workflow re-evaluates within 15 minutes of a change. To evaluate a single segment right now:

POST /v1/admin/projects/:projectId/segments/:id/evaluate

The evaluation runs in the background. The response confirms it started: { "data": { "status": "evaluating", "segment_id": "<id>" } }.

3. Verify membership

GET /v1/admin/projects/:projectId/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_push_campaigns_create({
  project_id: "proj_xxx",
  title: "New this week",
  body: "Fresh content is waiting for you.",
  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 user in the project.
• 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 target push campaigns at them.

How rules compose

Conditions are ANDed or ORed under a top-level operator. Each condition is { field, op, value }, and groups can nest up to five levels deep (see Composing rules).

{
  "operator": "OR",
  "conditions": [
    { "field": "created_at", "op": "within", "value": "7d" },
    { "field": "entitlements.is_active", "op": "eq", "value": true }
  ]
}

See Operators for the 12 supported comparators.

Performance

Rule evaluation runs as a single optimized query against the user index. Property paths and interval amounts are passed as bound parameters, and only whitelisted fields are accepted — 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.