User Segments

Segments let you define groups of users based on rules. Use them to target push campaigns or analyze engagement patterns.

How it works

A segment has a set of rules with an AND or OR operator combining conditions. Each condition evaluates a user property against a value using one of 12 operators.

Segment membership is re-evaluated within 15 minutes of a change to your users' data. Rules with a time window (within / not_within) also follow the clock: a user who crosses a window under a day joins or leaves within 15 minutes, and within the hour for longer windows. See Evaluation cadence.

Operators

Available fields

You can target any field on the user record:

• last_seen_at — last activity timestamp
• created_at — account creation date
• email — user email
• properties.* — custom user properties (e.g., properties.plan, properties.age). A properties.* comparison follows the type of the rule's value: a string compares with the property's text ({ field: "properties.plan", op: "eq", value: "pro" } matches plan: "pro"), a number compares numerically and counts a JSON number or a numeric string (gt 9 matches 10), and a boolean matches true / false or the strings "true" / "false". An object or array value supports eq / neq against the whole JSON value. A user without the property matches none of these operators.
• entitlements.is_active — active entitlement status

Admin API reference

POST /v1/admin/projects/:projectId/segments — Create segment

Body:

{
  "name": "Active Subscribers",
  "description": "Users 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 }
    ]
  }
}

System segments

Every project comes with built-in system segments that cannot be edited or deleted:

• All Users — every user in the project
• Active (7d) — users seen in the last 7 days
• Active (30d) — users seen in the last 30 days
• New Users — users created in the last 7 days

MCP tools

Example

Agent: "Create a segment for users who haven't opened the app in 14 days"

amba_segments_create({
  project_id: "proj_xxx",
  name: "Inactive 14d",
  description: "Users who haven't opened the app in 14 days",
  rules: {
    operator: "AND",
    conditions: [
      { field: "last_seen_at", op: "not_within", value: "14d" }
    ]
  }
})

What can target a segment