Skip to main content
Most segments are best authored in the Spotzee UI. Operators iterate quickly, preview membership, and version their work. Use the API when the rules themselves are derived from your code or config: a generated cohort per pricing plan, a per-region segment driven by a feature-flag rollout, or a backfill that needs to recreate dozens of segments at once.
Today the API exposes segments as dynamic lists. There is no separate /segments endpoint. A segment is a list with type: "dynamic" and a rule tree. Static lists (explicit member add/remove) use the same endpoints with type: "static".

​
What you’ll build

A script that creates a dynamic list with a rule tree, then walks its members.

​
Prerequisites

You’ll need a sk_ project key with write access. See Authentication.

​
Walkthrough

1

Decide what membership means

A segment is a boolean rule that yields true or false for any user. Common shapes:
  • Attribute filter: data.plan = "professional"
  • Behavioural filter: users who triggered order_placed in the last 30 days
  • Combined: plan = "professional" AND triggered order_placed in the last 30 days
Sketch the rule as plain language first; the JSON shape follows from there.
2

Build the rule tree

Spotzee rules are a tree of nodes. The root is a wrapper node that combines its children with and / or; leaves are typed comparisons against a user field (group: "user") or event payload (group: "event").Every node carries:Example: users on the Pro plan who triggered order_placed at least once in the last 30 days.
Refer to the RuleNode, RuleType, RuleGroup, and RuleFrequency schemas in the API reference for the exact enum values.
3

Create the list

POST /lists with type: "dynamic":
The response includes the list id. Save it. That’s how you’ll reference the segment from journeys, campaigns, and member-listing endpoints.
4

Verify membership

Members are computed asynchronously, so give Spotzee a moment after creation. The current public API does not expose a “members of a list” endpoint. Verify the list resolved as expected by inspecting it in the Spotzee UI, or by issuing a representative GET /users?q=… query that exercises the same attributes the rule depends on.
5

Update the rule

PATCH /lists/{listId} with a new rule block. Spotzee re-computes membership in the background. Existing members are reconciled: those who still match stay, those who don’t drop out.

​
Pitfalls to avoid

Don’t build a hot loop that recreates the same segment every minute. Recomputation is cheap but not free. Update the rule in place with PATCH rather than deleting and recreating.
  • Don’t filter on fields you haven’t populated yet. A rule on data.plan returns zero members until at least one user has that field. Sync your users first (Sync users), then build segments.
  • Don’t bury the rule in too many layers. Spotzee accepts deeply nested groups, but a rule that spans more than two and/or layers is hard for operators to read in the UI.

​
Reference