Segments

The kraiter.segments namespace provides methods for defining and computing dynamic audience segments. A segment is a rule-based grouping of contacts that is recomputed on demand.

Segment rules

A segment's rules are a recursive boolean expression tree, not a flat list. Each node has an operator ("and", "or", or "not") and a conditions array whose entries are either individual conditions or nested rule nodes.

An individual condition is one of:

Type	Shape	Description
`property`	`{ type: 'property', field, operator, value? }`	Matches against a contact property.
`derived`	`{ type: 'derived', field, operator, value? }`	Matches against a server-derived field.
`segment`	`{ type: 'segment', segmentId, operator }`	Matches on membership of another segment. `operator` is `'memberOf'` or `'notMemberOf'`.

const rules = {
  operator: 'and',
  conditions: [
    { type: 'property', field: 'plan', operator: 'equals', value: 'pro' },
    { type: 'derived', field: 'lastActiveAt', operator: 'after', value: '2025-01-01T00:00:00Z' },
  ],
};

create

Creates a new segment.

const segment = await kraiter.segments.create({
  name: 'Active Pro Users',
  description: 'Pro-plan contacts active this year',
  rules: {
    operator: 'and',
    conditions: [
      { type: 'property', field: 'plan', operator: 'equals', value: 'pro' },
      { type: 'derived', field: 'lastActiveAt', operator: 'after', value: '2025-01-01T00:00:00Z' },
    ],
  },
  enabled: true,
});

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	A human-readable name for the segment.
`description`	`string`	No	A longer description of the segment.
`rules`	`SegmentRules`	Yes	The boolean expression tree defining membership (see Segment rules).
`enabled`	`boolean`	No	Whether the segment is enabled for evaluation.

Returns

Promise<Segment> — the newly created segment object.

Errors

Code	When
`VALIDATION_ERROR`	The rules tree is empty or contains invalid conditions.

get

Retrieves a segment by ID. Returns null if not found.

const segment = await kraiter.segments.get('seg_abc123');

if (segment) {
  console.log(segment.name, segment.memberCount);
}

Parameters

Parameter	Type	Required	Description
`segmentId`	`string`	Yes	The segment ID.

Returns

Promise<Segment | null> — the segment object, or null if not found.

list

Lists segments with cursor-based pagination.

const page = await kraiter.segments.list({ limit: 50 });

for (const segment of page.items) {
  console.log(segment.segmentId, segment.name);
}

Parameters

Parameter	Type	Required	Description
`limit`	`number`	No	Maximum items per page.
`cursor`	`string`	No	Pagination cursor from a previous response's `nextCursor`.

Returns

Promise<{ items: Segment[]; nextCursor?: string }> — a page of segment objects.

update

Updates an existing segment. Only the fields you include are changed.

const updated = await kraiter.segments.update('seg_abc123', {
  name: 'Active Enterprise Users',
  rules: {
    operator: 'and',
    conditions: [
      { type: 'property', field: 'plan', operator: 'equals', value: 'enterprise' },
    ],
  },
});

Parameters

Parameter	Type	Required	Description
`segmentId`	`string`	Yes	The segment ID to update.
`name`	`string`	No	Updated segment name.
`description`	`string`	No	Updated description.
`rules`	`SegmentRules`	No	Updated rules tree.
`enabled`	`boolean`	No	Whether the segment is enabled.

Returns

Promise<Segment> — the updated segment object.

Errors

Code	When
`NOT_FOUND`	No segment exists with this ID.
`VALIDATION_ERROR`	The updated rules are invalid.

delete

Permanently deletes a segment.

await kraiter.segments.delete('seg_abc123');

Parameters

Parameter	Type	Required	Description
`segmentId`	`string`	Yes	The segment ID to delete.

Returns

Promise<void>

Errors

Code	When
`NOT_FOUND`	No segment exists with this ID.

compute

Triggers a recomputation of segment membership. This evaluates the segment rules against all contacts and updates the membership list.

const result = await kraiter.segments.compute('seg_abc123');

console.log(result.processed); // contacts evaluated
console.log(result.changed);   // memberships that changed

Parameters

Parameter	Type	Required	Description
`segmentId`	`string`	Yes	The segment ID to recompute.

Returns

Promise<ComputeSegmentResult> — an object with segmentId, processed (number of contacts evaluated), and changed (number of memberships that changed).

listMembers

Lists the membership records for a segment, with cursor-based pagination. Membership is based on the last computation — call compute first if you need fresh results.

// Recompute then list
await kraiter.segments.compute('seg_abc123');

const page = await kraiter.segments.listMembers('seg_abc123');

for (const member of page.items) {
  console.log(member.contactId, member.isMember, member.computedAt);
}

Parameters

Parameter	Type	Required	Description
`segmentId`	`string`	Yes	The segment ID.
`limit`	`number`	No	Maximum items per page.
`cursor`	`string`	No	Pagination cursor.

Returns

Promise<{ items: SegmentMember[]; nextCursor?: string }> — a page of membership records. Each SegmentMember has contactId, isMember, computedAt, and version.

Segments

On this page