Segments

Rule-based audiences over project user fields, attributes and tags, with nested and/or groups.

A segment is a saved, named condition tree. Target it with { "type": "segment", "segmentId": "seg_…" }. Membership is evaluated each time a user's feed loads (see read-time evaluation). Segments need the Growth plan and up (see plan features).

Shape

{
  "name": "Pro users in the beta",
  "description": "Pro plan and opted into the beta",
  "conditions": {
    "combinator": "and",
    "conditions": [
      { "field": "attributes.plan", "operator": "eq", "value": "pro" },
      { "field": "tags", "operator": "contains", "value": "beta" }
    ]
  }
}

A group has a combinator (and or or) and a list of conditions, each either a condition (field, operator, value) or another group.

Fields

Operators

Comparison rules:

• String comparisons are case-insensitive (eq, in, contains, starts_with, ends_with).
• Lists: when the field is a list (such as tags or a string-array attribute), eq and contains match if any element matches.
• Numbers: if either side is a number, both are compared as numbers, so "42" equals 42. Booleans count as 1 and 0.
• Dates: gt/gte/lt/lte convert strings to numbers, and strings that aren't numbers are parsed as dates. { "field": "createdAt", "operator": "gte", "value": "2026-01-01" } compares against midnight UTC on 1 January 2026.
• Values can be a string (up to 1,024 characters), number, boolean, null or a list of up to 100 strings. in and not_in need a list.

Nesting and limits

{
  "combinator": "and",
  "conditions": [
    { "field": "attributes.plan", "operator": "in", "value": ["pro", "team"] },
    {
      "combinator": "or",
      "conditions": [
        { "field": "locale", "operator": "starts_with", "value": "de" },
        { "field": "timezone", "operator": "in", "value": ["Europe/Berlin", "Europe/Vienna"] }
      ]
    },
    { "field": "createdAt", "operator": "gte", "value": "2026-01-01" }
  ]
}

Preview before saving

POST /v1/segments/preview evaluates a condition tree over up to 1,000 of the most recently active project users and returns how many matched, plus up to five examples. It's an estimate for sanity checks, not an exact count, and it doesn't write anything. It works on every plan, even without an active subscription.

curl https://api.notificationstream.com/v1/segments/preview \
  -H "Authorization: Bearer $NOTIFICATIONSTREAM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conditions":{"combinator":"and","conditions":[{"field":"attributes.plan","operator":"eq","value":"pro"}]}}'

{ "sampled": 1000, "matched": 132, "examples": [{ "userId": "user_123", "email": "ada@example.com", "name": "Ada Lovelace" }] }

Manage segments