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.

create

Creates a new segment with a set of rules.

const segment = await kraiter.segments.create({
  name: 'Active Pro Users',
  rules: [
    { field: 'properties.plan', operator: 'equals', value: 'pro' },
    { field: 'lastActiveAt', operator: 'after', value: '2025-01-01T00:00:00Z' },
  ],
});

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	A human-readable name for the segment.
`rules`	`SegmentRule[]`	Yes	An array of rules that define segment membership. All rules must match for a contact to be included (AND logic).

SegmentRule object

Field	Type	Description
`field`	`string`	The contact field or property path to evaluate (e.g. `email`, `properties.plan`, `lastActiveAt`).
`operator`	`string`	The comparison operator. Supported values: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `before`, `after`, `gt`, `lt`, `gte`, `lte`, `exists`, `not_exists`.
`value`	`unknown`	The value to compare against. Type depends on the operator and field.

Returns

Promise<Segment> — the newly created segment object.

Errors

Code	When
`VALIDATION_ERROR`	The rules array is empty or contains invalid operators.

get

Retrieves a segment by ID.

const segment = await kraiter.segments.get('seg_abc123');
console.log(segment.name, segment.rules.length);

Parameters

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

Returns

Promise<Segment> — the segment object.

Errors

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

list

Lists all segments. Returns an async iterator.

for await (const segment of kraiter.segments.list()) {
  console.log(segment.id, segment.name);
}

Parameters

Parameter	Type	Required	Description
`cursor`	`string`	No	Pagination cursor.
`limit`	`number`	No	Maximum items per page.

Returns

AsyncIterable<Segment> — an async iterator of segment objects.

update

Updates an existing segment. You can change the name, the rules, or both.

const updated = await kraiter.segments.update('seg_abc123', {
  name: 'Active Enterprise Users',
  rules: [
    { field: 'properties.plan', operator: 'equals', value: 'enterprise' },
    { field: 'lastActiveAt', operator: 'after', value: '2025-01-01T00:00:00Z' },
  ],
});

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The segment ID to update.
`name`	`string`	No	Updated segment name.
`rules`	`SegmentRule[]`	No	Updated rules array.

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
`id`	`string`	Yes	The segment ID to delete.

Errors

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

Triggers a recomputation of segment membership. This evaluates the segment rules against all contacts and updates the membership list. The method returns once the computation has been queued — membership updates may take a few moments to complete for large contact lists.

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

Parameters

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

Returns

Promise<void>

Errors

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

getMembers

Lists the contacts that belong to a segment. Returns an async iterator. Membership is based on the last computation — call compute first if you need fresh results.

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

for await (const contact of kraiter.segments.getMembers('seg_abc123')) {
  console.log(contact.email);
}

Parameters

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

Returns

AsyncIterable<Contact> — an async iterator of contact objects belonging to the segment.

Errors

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

Segments

On this page