PushizoDocs
Users & segments

Segments

Dynamic and static segments, the condition AST (all/any/none), field and operator list, behavior and location conditions, preview/estimate endpoints and campaign usage.

A segment is a saved condition tree that selects users (and their subscriptions). Dynamic segments are recomputed on every send; static segments are frozen with POST …/segments/{id}/refresh or via import. The same condition language is used in target.filters inside POST /v1/notifications, in POST …/users/search, and in in-app/journey audiences.

Condition language

{
  "all": [
    { "field": "tag", "name": "plan", "op": "eq", "value": "pro" },
    { "field": "last_active_at", "op": "within_days", "days": 30 },
    { "any": [
      { "field": "event", "name": "purchase", "op": "count_gte", "value": 3, "days": 90 },
      { "field": "property", "name": "ltv", "op": "gt", "value": 500 }
    ] },
    { "none": [ { "field": "message", "event": "opened", "op": "has", "within_days": 7 } ] }
  ]
}

Groups: all (AND), any (OR), none (NOT); they can be nested (at most 50 conditions per group; the compiler limits depth). Each condition carries field, op and, where needed, name/value/days.

Fields

fieldDescriptionExtra keys
tagUser tagname
propertyTyped property (numeric comparison)name
language, country, timezoneSubscription/user metadata—
device_type, device_os, app_versionDevice; app_version compares semver—
channel, subscription_statusSubscription channel/status—
first_session_at, last_active_at, created_atTime fieldsdays
session_count, usage_durationSession count / total duration—
eventEvent count (user_event_counts)name, days, where ({ key, value } property filter)
messageMessage behavior: sent, delivered, failed, bounced, opened, clickedevent, within_days, message_id, campaign_id, journey_id, channel
in_appIn-app behavior: impression, clicked, dismissedevent, within_days, in_app_message_id
segmentMembership in another segmentvalue (segment id)
locationWithin a radius (location)lat, lng, radius_km, days

Operators

GroupOperators
Comparisoneq, neq, exists, not_exists, contains, starts_with, gt, lt, gte, lte, in, not_in, between
Timewithin_days (within the last N days), before_days (older than N days)
Versionsemver_gte, semver_lt (app_version)
Event countcount_gte, count_lte, not_performed (event)
Behaviorhas, has_not (message, in_app)
Locationwithin_radius (location)

Field × operator validity is checked by the compiler; an incompatible combination returns 400 HS_VALIDATION_ERROR. Schema: API → schemas.

API

OperationEndpointScope
ListGET /v1/apps/{app_id}/segments?q=&cursor=segments:read
Create / update / deletePOST, PATCH …/{id}, DELETE …/{id} (a segment in use returns 409)admin
Preview (without saving)POST …/segments/preview { definition } → count + sample userssegments:read
EstimatePOST …/segments/{id}/estimate → cached count (channel breakdown)segments:read
Static refreshPOST …/segments/{id}/refreshadmin
Campaigns using itGET …/segments/{id}/campaignssegments:read

Examples: API → Segments. Use included_segments / excluded_segments in campaigns and notifications; segment counts are shown per channel for the email/SMS channels.

Performance and behavior

  • Conditions are compiled to parameterized SQL; event counts are read from the user_event_counts table (user × event × day), with no raw event scans.
  • Estimates are cached briefly (dashboard counter); the exact audience is computed at send time and returned as recipients_estimate.
  • Segment conditions do not look at subscription status; at send time, only active subscriptions are used and channel/preference/suppression filters are applied.
  • The dashboard's Audience → Segments shows the visual builder, live count and campaign usage; on the Users page, the same builder applies ad-hoc filters.

On this page